docs: list/import/fetch: document --config/--remote/--remote-config

Fixes #4712
iterative · Aug 6, 2023 · 84a1c5b · 84a1c5b
1 parent 8d72170
commit 84a1c5b
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 7 deletions.
diff --git a/content/docs/command-reference/get.md b/content/docs/command-reference/get.md
@@ -9,7 +9,10 @@ directory.
 
 ```usage
 usage: dvc get [-h] [-q | -v] [-o <path>] [--rev <commit>]
-               [--show-url] [-j <number>] [-f] url path
+               [--show-url] [-j <number>] [-f]
+               [--config <path>] [--remote <name>]
+               [--remote-config [<name>=<value> ...]]
+               url path
 
 positional arguments:
   url              Location of DVC or Git repository to download from
@@ -82,6 +85,16 @@ name.
   storage location (URL) of the target data. If `path` is a Git-tracked file,
   this option is ignored.
 
+- `--config <path>` - path to a [config file](/doc/command-reference/config)
+  that will be merged with the config in the target repository.
+
+- `--remote <name>` - name of the `dvc remote` to set as a default in the target
+  repository.
+
+- `--remote-config [<name>=<value> ...]` - `dvc remote` config options to merge
+  with a remote's config (default or one specified by `--remote`) in the target
+  repository.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no
@@ -219,3 +232,15 @@ Untracked files:
 [get started example repo]: https://github.com/iterative/example-get-started
 [switching between versions]:
   /doc/start/data-management/data-versioning#switching-between-versions
+
+## Example: set AWS profile for default remote
+
+```
+$ dvc get URL path --remote-config profile=myprofile
+```
+
+## Example: set default remote
+
+```
+$ dvc get URL path --remote myremote
+```
diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md
@@ -12,6 +12,8 @@ usage: dvc import [-h] [-q | -v]
                   [-o <path>] [--rev <commit>]
                   [--no-exec | --no-download]
                   [-j <number>]
+                  [--config <path>] [--remote <name>]
+                  [--remote-config [<name>=<value> ...]]
                   url path
 
 positional arguments:
@@ -118,6 +120,16 @@ file.
   speed up the operation. Note that the default value can be set in the source
   repo using the `jobs` config option of `dvc remote modify`.
 
+- `--config <path>` - path to a [config file](/doc/command-reference/config)
+  that will be merged with the config in the target repository.
+
+- `--remote <name>` - name of the `dvc remote` to set as a default in the target
+  repository.
+
+- `--remote-config [<name>=<value> ...]` - `dvc remote` config options to merge
+  with a remote's config (default or one specified by `--remote`) in the target
+  repository.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no
@@ -386,3 +398,15 @@ C, otherwise the import chain resolution would fail.
 
 The `dvc remote default` for all repos in the import chain must also be
 accessible (repo C needs to have all the appropriate credentials).
+
+## Example: set AWS profile for default remote
+
+```
+$ dvc import URL path --remote-config profile=myprofile
+```
+
+## Example: set default remote
+
+```
+$ dvc import URL path --remote myremote
+```
diff --git a/content/docs/command-reference/list.md b/content/docs/command-reference/list.md
@@ -12,6 +12,8 @@ and by Git.
 ```usage
 usage: dvc list [-h] [-q | -v] [-R] [--dvc-only]
                 [--json] [--rev [<commit>]]
+                [--config <path>] [--remote <name>]
+                [--remote-config [<name>=<value> ...]]
                 url [path]
 
 positional arguments:
@@ -71,6 +73,16 @@ accessed with `dvc get`, `dvc import`, or `dvc.api`.
 - `--json` - prints the command's output in easily parsable JSON format, instead
   of a human-readable table.
 
+- `--config <path>` - path to a [config file](/doc/command-reference/config)
+  that will be merged with the config in the target repository.
+
+- `--remote <name>` - name of the `dvc remote` to set as a default in the target
+  repository.
+
+- `--remote-config [<name>=<value> ...]` - `dvc remote` config options to merge
+  with a remote's config (default or one specified by `--remote`) in the target
+  repository.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no
@@ -161,3 +173,15 @@ installed):
 ```cli
 $ dvc list . -R --dvc-only | xargs python -m zipfile -c data.zip
 ```
+
+## Example: set AWS profile for default remote
+
+```
+$ dvc list URL path --remote-config profile=myprofile
+```
+
+## Example: set default remote
+
+```
+$ dvc list URL path --remote myremote
+```
diff --git a/content/docs/user-guide/project-structure/dvc-files.md b/content/docs/user-guide/project-structure/dvc-files.md
@@ -73,14 +73,16 @@ The following subfields may be present under `deps` entries:
 | `md5`<br/>`etag`<br/>`checksum` | Only in <abbr>external dependencies</abbr> created with `dvc import-url`: Hash value of the imported file or directory. MD5 is used for local paths and SSH; [ETag] for HTTP, S3, GCS, and Azure; and a special _checksum_ for HDFS and WebHDFS. |
 | `size`                          | Size of the file or directory (sum of all files).                                                                                                                                                                                                |
 | `nfiles`                        | If this dependency is a directory, the number of files inside (recursive).                                                                                                                                                                       |
-| `repo`                          | Only in external dependencies created with `dvc import`: It can contain `url`, `rev`, and `rev_lock` (detailed below).                                                                                                                           |
+| `repo`                          | Only in external dependencies created with `dvc import`: It can contain `url`, `rev`, `rev_lock`, `config` and `remote` (detailed below).                                                                                                        |
 
 ### Dependency `repo` subfields:
 
-| Field      | Description                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`      | URL of Git repository with source DVC project                                                                                               |
-| `rev`      | Only when `dvc import --rev` is used: Specific commit hash, branch or tag name, etc. (a [Git revision]) used to import the dependency from. |
-| `rev_lock` | Git commit hash of the external <abbr>DVC repository</abbr> at the time of importing or updating the dependency (with `dvc update`)         |
+| Field      | Description                                                                                                                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`      | URL of Git repository with source DVC project                                                                                                                                                         |
+| `rev`      | Only when `dvc import --rev` is used: Specific commit hash, branch or tag name, etc. (a [Git revision]) used to import the dependency from.                                                           |
+| `rev_lock` | Git commit hash of the external <abbr>DVC repository</abbr> at the time of importing or updating the dependency (with `dvc update`)                                                                   |
+| `config`   | Only when `dvc import --config` is used: Path to a [config file](/doc/command-reference/config) that will be merged with the config in the target repository.                                         |
+| `remote`   | Only when `dvc import --remote` or `--remote-config` is used: name of the `dvc remote` to set as a default or remote config options to merge with a default remote's config in the target repository. |
 
 [git revision]: https://git-scm.com/docs/revisions