From 9f7b3d97db31f0376f445502d80ad9084c25a91f Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 5 Aug 2020 21:14:07 -0500 Subject: [PATCH 01/11] cmd: remove unnecessary commas in get and import --- content/docs/command-reference/get.md | 2 +- content/docs/command-reference/import.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/get.md b/content/docs/command-reference/get.md index d09a375804..b3b54c94d9 100644 --- a/content/docs/command-reference/get.md +++ b/content/docs/command-reference/get.md @@ -39,7 +39,7 @@ downloading, DVC will try to copy the target data from its cache). The `path` argument is used to specify the location of the target to download within the source repository at `url`. `path` can specify any file or directory in the source repo, either tracked by DVC (including paths inside tracked -directories), or by Git. Note that DVC-tracked targets should be found in a +directories) or by Git. Note that DVC-tracked targets should be found in a `dvc.yaml` or `.dvc` file of the project. ⚠️ The project should have a default diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md index c504be21c1..7b1a131e91 100644 --- a/content/docs/command-reference/import.md +++ b/content/docs/command-reference/import.md @@ -42,7 +42,7 @@ downloading, DVC will try to copy the target data from its cache). The `path` argument is used to specify the location of the target to download within the source repository at `url`. `path` can specify any file or directory in the source repo, either tracked by DVC (including paths inside tracked -directories), or by Git. Note that DVC-tracked targets should be found in a +directories) or by Git. Note that DVC-tracked targets should be found in a `dvc.yaml` or `.dvc` file of the project. ⚠️ The project should have a default From c0f7748857e8a019d11245a69bda6aa4ad89f9d2 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 5 Aug 2020 21:14:27 -0500 Subject: [PATCH 02/11] cmd: fix typo in add --- content/docs/command-reference/remote/add.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/remote/add.md b/content/docs/command-reference/remote/add.md index adc643d7aa..524eb9ce1d 100644 --- a/content/docs/command-reference/remote/add.md +++ b/content/docs/command-reference/remote/add.md @@ -24,8 +24,8 @@ or even a directory in the local file system. (See all the supported remote storage types in the examples below.) If `url` is a relative path, it will be resolved against the current working directory, but saved **relative to the config file location** (see LOCAL example below). Whenever possible, DVC will -create a remote directory if it doesn't exists yet. (It won't create an S3 -bucket though, and will rely on default access settings.) +create a remote directory if it doesn't exist yet. (It won't create an S3 bucket +though, and will rely on default access settings.) > If you installed DVC via `pip` and plan to use cloud services as remote > storage, you might need to install these optional dependencies: `[s3]`, From 308a23dbaac6eb782c254b731974d465a7dd0e54 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 02:44:13 -0500 Subject: [PATCH 03/11] cmd: remote copy edits per https://github.com/iterative/dvc.org/pull/1617#discussion_r465675597 --- content/docs/command-reference/remote/add.md | 3 +- .../docs/command-reference/remote/modify.md | 86 +++++++++++-------- 2 files changed, 50 insertions(+), 39 deletions(-) diff --git a/content/docs/command-reference/remote/add.md b/content/docs/command-reference/remote/add.md index 524eb9ce1d..7fca263aa7 100644 --- a/content/docs/command-reference/remote/add.md +++ b/content/docs/command-reference/remote/add.md @@ -131,7 +131,8 @@ For example: ```dvc $ dvc remote add -d myremote s3://mybucket/path/to/dir -$ dvc remote modify myremote endpointurl https://object-storage.example.com +$ dvc remote modify myremote endpointurl \ + https://object-storage.example.com ``` > See `dvc remote modify` for a full list of S3 API parameters. diff --git a/content/docs/command-reference/remote/modify.md b/content/docs/command-reference/remote/modify.md index 279a791719..ce9211a97d 100644 --- a/content/docs/command-reference/remote/modify.md +++ b/content/docs/command-reference/remote/modify.md @@ -90,19 +90,19 @@ these settings, you could use the following options: $ dvc remote modify myremote region us-east-2 ``` -- `profile` - credentials profile name to use to access S3: +- `profile` - credentials profile name to access S3: ```dvc $ dvc remote modify myremote profile myprofile ``` -- `credentialpath` - credentials path to use to access S3: +- `credentialpath` - credentials path to access S3: ```dvc $ dvc remote modify myremote credentialpath /path/to/my/creds ``` -- `endpointurl` - endpoint URL to use to access S3: +- `endpointurl` - endpoint URL to access S3: ```dvc $ dvc remote modify myremote endpointurl https://myendpoint.com @@ -168,21 +168,24 @@ these settings, you could use the following options: for specific grantees\*\*. Grantee can read object and its metadata. ```dvc - $ dvc remote modify myremote grant_read id=aws-canonical-user-id,id=another-aws-canonical-user-id + $ dvc remote modify myremote grant_read \ + id=aws-canonical-user-id,id=another-aws-canonical-user-id ``` - `grant_read_acp`\* - grants `READ_ACP` permissions at object level access control list for specific grantees\*\*. Grantee can read the object's ACP. ```dvc - $ dvc remote modify myremote grant_read_acp id=aws-canonical-user-id,id=another-aws-canonical-user-id + $ dvc remote modify myremote grant_read_acp \ + id=aws-canonical-user-id,id=another-aws-canonical-user-id ``` - `grant_write_acp`\* - grants `WRITE_ACP` permissions at object level access control list for specific grantees\*\*. Grantee can modify the object's ACP. ```dvc - $ dvc remote modify myremote grant_write_acp id=aws-canonical-user-id,id=another-aws-canonical-user-id + $ dvc remote modify myremote grant_write_acp \ + id=aws-canonical-user-id,id=another-aws-canonical-user-id ``` - `grant_full_control`\* - grants `FULL_CONTROL` permissions at object level @@ -190,7 +193,8 @@ these settings, you could use the following options: grant_read_acp + grant_write_acp ```dvc - $ dvc remote modify myremote grant_full_control id=aws-canonical-user-id,id=another-aws-canonical-user-id + $ dvc remote modify myremote grant_full_control \ + id=aws-canonical-user-id,id=another-aws-canonical-user-id ``` > \* `grant_read`, `grant_read_acp`, `grant_write_acp` and @@ -221,7 +225,8 @@ For example: ```dvc $ dvc remote add myremote s3://path/to/dir -$ dvc remote modify myremote endpointurl https://object-storage.example.com +$ dvc remote modify myremote endpointurl \ + https://object-storage.example.com ``` S3 remotes can also be configured entirely via environment variables: @@ -250,7 +255,8 @@ For more information about the variables DVC supports, please visit - `connection_string` - connection string. ```dvc - $ dvc remote modify --local myremote connection_string "my-connection-string" + $ dvc remote modify --local myremote connection_string \ + "my-connection-string" ``` > The connection string contains sensitive user info. Therefore, it's safer to @@ -274,8 +280,8 @@ a full guide on using Google Drive as DVC remote storage. [possible formats](/doc/user-guide/setup-google-drive-remote#url-format). ```dvc - $ dvc remote modify myremote \ - url gdrive://0AIac4JZqHhKmUk9PDA/dvcstore + $ dvc remote modify myremote url \ + gdrive://0AIac4JZqHhKmUk9PDA/dvcstore ``` - `gdrive_client_id` - Client ID for authentication with OAuth 2.0 when using a @@ -415,13 +421,13 @@ more information. $ dvc remote modify myremote oss_endpoint endpoint ``` -- `oss_key_id` - OSS key ID to use to access a remote. +- `oss_key_id` - OSS key ID to access the remote. ```dvc $ dvc remote modify myremote --local oss_key_id my-key-id ``` -- `oss_key_secret` - OSS secret key for authorizing access into a remote. +- `oss_key_secret` - OSS secret key for authorizing access into the remote. ```dvc $ dvc remote modify myremote --local oss_key_secret my-key-secret @@ -440,41 +446,43 @@ more information. - `url` - remote location URL. ```dvc - $ dvc remote modify myremote url ssh://user@example.com:1234/path/to/remote + $ dvc remote modify myremote url \ + ssh://user@example.com:1234/absolute/path ``` -- `user` - username to use to access a remote. The order in which dvc searches - for username: - - 1. `user` specified in one of the dvc configs; - 2. `user` specified in the url(e.g. `ssh://user@example.com/path`); - 3. `user` specified in `~/.ssh/config` for remote host; - 4. current user; +- `user` - username to access the remote. ```dvc $ dvc remote modify --local myremote user myuser ``` -- `port` - port to use to access a remote. The order in which dvc searches for - port: + The order in which DVC picks the username: - 1. `port` specified in one of the dvc configs; - 2. `port` specified in the url(e.g. `ssh://example.com:1234/path`); - 3. `port` specified in `~/.ssh/config` for remote host; - 4. default ssh port 22; + 1. `user` parameter set with this command (found in `.dvc/config`); + 2. User defined in the URL (e.g. `ssh://user@example.com/path`); + 3. User defined in `~/.ssh/config` for this host (URL); + 4. Current user + +- `port` - port to access the remote. ```dvc $ dvc remote modify myremote port 2222 ``` -- `keyfile` - path to private key to use to access a remote. + The order in which DVC decide the port number: + + 1. `port` parameter set with this command (found in `.dvc/config`); + 2. Port defined in the URL (e.g. `ssh://example.com:1234/path`); + 3. Port defined in `~/.ssh/config` for this host (URL); + 4. Default SSH port 22 + +- `keyfile` - path to private key to access the remote. ```dvc $ dvc remote modify myremote keyfile /path/to/keyfile ``` -- `password` - a private key passphrase or a password to use to use when - accessing a remote. +- `password` - a private key passphrase or a password to access the remote. ```dvc $ dvc remote modify --local myremote password mypassword @@ -484,8 +492,8 @@ more information. > safer to add them with the `--local` option, so they're written to a > Git-ignored config file. -- `ask_password` - ask for a private key passphrase or a password to use when - accessing a remote. +- `ask_password` - ask for a private key passphrase or a password to access the + remote. ```dvc $ dvc remote modify myremote ask_password true @@ -509,7 +517,7 @@ more information. ### Click for HDFS -- `user` - username to use to access a remote. +- `user` - username to access the remote. ```dvc $ dvc remote modify --local myremote user myuser @@ -524,7 +532,7 @@ more information. ### Click for HTTP -- `auth` - authentication method to use when accessing a remote. The accepted +- `auth` - authentication method to use when accessing the remote. The accepted values are: - `basic` - @@ -551,15 +559,17 @@ more information. ``` - `user` - username to use when the `auth` parameter is set to `basic` or - `digest`. The order in which DVC searches for username: - - 1. `user` specified in one of the DVC configs; - 2. `user` specified in the url(e.g. `http://user@example.com/path`); + `digest`. ```dvc $ dvc remote modify --local myremote user myuser ``` + The order in which DVC picks the username: + + 1. `user` parameter set with this command (found in `.dvc/config`); + 2. User defined in the URL (e.g. `http://user@example.com/path`); + - `password` - password to use for any `auth` method. ```dvc From 56349a7ba703fbaec1e69757b236d54676366d46 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 12:23:26 -0500 Subject: [PATCH 04/11] guide: .dvcignore copy edit --- content/docs/user-guide/dvcignore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/dvcignore.md b/content/docs/user-guide/dvcignore.md index 69af83366d..7305abe11b 100644 --- a/content/docs/user-guide/dvcignore.md +++ b/content/docs/user-guide/dvcignore.md @@ -16,7 +16,7 @@ similar to `.gitignore` in Git. - You need to create the `.dvcignore` file. It can be placed in the root of the project or inside any subdirectory (see also [remarks](#Remarks) below). - Populate it with [patterns](https://git-scm.com/docs/gitignore) that you would - like to ignore. You can find useful file templates + like to ignore. You can find useful templates [here](https://github.com/github/gitignore). - Each line should contain only one pattern. - During execution of commands that traverse directories, DVC will ignore From dbb9b9462e7b3c959f7bf7e87b3363014857ea35 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 12:29:44 -0500 Subject: [PATCH 05/11] cmd: init copy edits --- content/docs/command-reference/init.md | 38 +++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/content/docs/command-reference/init.md b/content/docs/command-reference/init.md index 365499f15b..2c4115fb75 100644 --- a/content/docs/command-reference/init.md +++ b/content/docs/command-reference/init.md @@ -32,45 +32,45 @@ advanced scenarios: ### Initializing DVC in subdirectories `--subdir` must be provided to initialize DVC in a subdirectory of a Git -repository. DVC still expects to find the Git repository (will check all -directories up to the system root to find `.git/`). This options does not affect -any config files, `.dvc/` directory is created the same way as in the default -mode. This way multiple DVC projects can be initialized in a single -Git repository, providing isolation between projects. +repository. DVC still expects to find a Git root (will check all directories up +to the system root to find `.git/`). This options does not affect any config +files, `.dvc/` directory is created the same way as in the default mode. This +way multiple DVC projects can be initialized in a single Git +repository, providing isolation between projects. #### When is this useful? This option is mostly useful in the scenario of a -[monorepo](https://en.wikipedia.org/wiki/Monorepo) (Git repository split into -several project directories), but can also be used with other patterns when such -isolation is needed. `dvc init --subdir` mitigates the issues of initializing -DVC in the Git repo root: +[monorepo](https://en.wikipedia.org/wiki/Monorepo) (Git repo split into several +project directories), but can also be used with other patterns when such +isolation is needed. `dvc init --subdir` mitigates possible limitations of +initializing DVC in the Git repo root: - Repository maintainers might not allow a top level `.dvc/` directory, - especially if DVC is being used by several sub-projects (monorepo). + especially if DVC is already being used by several sub-projects (monorepo). - DVC [internals](/doc/user-guide/dvc-files-and-directories) (config file, cache - directory, etc.) are shared across different sub-projects. This forces all of - them to use the same DVC settings and + directory, etc.) would be shared across different subdirectories. This forces + all of them to use the same DVC settings and [remote storage](/doc/command-reference/remote). - By default, DVC commands like `dvc pull` and `dvc repro` explore the whole DVC repository to find DVC-tracked data and pipelines to work with. This can be inefficient for large monorepos. -- Other commands such as `dvc status` and `dvc metrics show` would produce - unexpected results if not constrained to a single project scope. +- Commands such as `dvc status` and `dvc metrics show` would produce unexpected + results if not constrained to a single project scope. #### How does it affect DVC commands? The project root is found by DVC by looking for `.dvc/` from the current working directory, up. It defines the scope of action for most DVC -commands (e.g. `dvc repro`, `dvc pull`, `dvc metrics diff`), meaning that only -`dvc.yaml`, `.dvc` files, etc. inside the project are usable by the commands. +commands (e.g. `dvc repro`, `dvc pull`, `dvc metrics diff`, etc.) meaning that +only `dvc.yaml`, `.dvc` files, etc. inside the project are usable by the +commands. -With `--subdir`, the project root will be found before the Git root, making sure -the scope of DVC commands run here is constrained to this project alone, even if -there are more DVC-related files elsewhere in the repo. +With `--subdir`, the project root will be found before the Git root, causing the +scope of DVC commands run here is constrained to this project alone. If there are multiple `--subdir` projects, but not nested, e.g.: From e71210b8bd9070931c1d3f820290a17b3195fae7 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 19:17:54 -0500 Subject: [PATCH 06/11] clarify about dirs in import -o --- content/docs/command-reference/import.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md index fe7afe57e7..2139e0ee24 100644 --- a/content/docs/command-reference/import.md +++ b/content/docs/command-reference/import.md @@ -75,11 +75,10 @@ from the source repo. ## Options -- `-o `, `--out ` - specify a path (directory and/or file name) to - the desired location to place the imported file in (instead of using the - current working directory). If an existing directory is specified, the target - data will be placed inside. If `path` contains a parent directory which does - not exist, this command will fail. +- `-o `, `--out ` - specify a path to the desired location to place + the imported file in the workspace (instead of using the current working + directory). Directories specified in the path should already exist, otherwise + this command will fail. - `--rev ` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to From 9e90a5eec641534a8f431f04e5d5ffb62a71de3a Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 21:26:58 -0500 Subject: [PATCH 07/11] cmd: review get -o desc --- content/docs/command-reference/get.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/content/docs/command-reference/get.md b/content/docs/command-reference/get.md index b3b54c94d9..efcfc1d5f2 100644 --- a/content/docs/command-reference/get.md +++ b/content/docs/command-reference/get.md @@ -55,11 +55,9 @@ name. ## Options -- `-o `, `--out ` - specify a path (directory and/or file name) to - the desired location to place the download file in. The default value (when - this option isn't used) is the current working directory (`.`) and original - file name. If an existing directory is specified, then the target data will be - placed inside. +- `-o `, `--out ` - specify a path to the desired location to place + the imported file in the workspace (instead of using the current working + directory). Directories specified in the path will be created by this command. - `--rev ` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to From 4cb410b1ee59875aadcb0715fe87f5d3f12593bb Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 6 Aug 2020 23:44:54 -0500 Subject: [PATCH 08/11] dvcignore: updates to guide and check-ignore ref. per https://github.com/iterative/dvc.org/pull/1629#pullrequestreview-463015446 et al. --- .../docs/command-reference/check-ignore.md | 30 ++++++++++--------- content/docs/user-guide/dvcignore.md | 2 +- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/content/docs/command-reference/check-ignore.md b/content/docs/command-reference/check-ignore.md index 4a99f6d591..c4a2cb07a5 100644 --- a/content/docs/command-reference/check-ignore.md +++ b/content/docs/command-reference/check-ignore.md @@ -10,7 +10,7 @@ usage: usage: dvc check-ignore [-h] [-q | -v] [-d] [-n] targets [targets ...] positional arguments: - targets File or directory paths to check (wildcards supported) + targets File or directory paths to check ``` ## Description @@ -19,16 +19,15 @@ This helper command checks whether the given `targets` are ignored by DVC according to the [`.dvcignore` file](/doc/user-guide/dvcignore) (if any). The ones that are ignored indeed are printed back. -> Note that your shell may support path wildcards such as `dir/file*` and these -> can be fed as `targets` to `dvc check-ignore`, as shown in the -> [examples](#examples). - ## Options -- `-d`, `--details` - show the exclude pattern together with each target path. +- `-d`, `--details` - show the exclude patterns along with each target path. A + series of lines are printed in this format: + `:: | ` -- `-n`, `--non-matching` - show the target paths which don’t match any pattern. - Only usable when `--details` is also employed +- `-n`, `--non-matching` - show the target paths which don’t match any pattern + in a `--details` list. All fields in each line, except for ``, + will be empty. Has no effect without `--details`. - `-h`, `--help` - prints the usage/help message, and exit. @@ -40,13 +39,14 @@ ones that are ignored indeed are printed back. ## Examples First, let's create a `.dvcignore` file with some patterns in it, and some files -to check against it. +to check against it: ```dvc $ echo "file*\n\!file2" >> .dvcignore $ cat .dvcignore file* !file2 + $ touch file1 file2 other $ ls file1 file2 other @@ -58,31 +58,33 @@ given our `.dvcignore` file: ```dvc $ dvc check-ignore file1 file1 + $ dvc check-ignore file1 file2 file1 file2 + $ dvc check-ignore other # There's no command output, meaning `other` is not excluded. + $ dvc check-ignore file* file1 file2 ``` -If the `--details` option is used, a series of lines are printed using this -format: `:: | ` +With `--details` (`-d`), we get a detailed report of all the matches: ```dvc $ dvc check-ignore -d file1 file2 .dvcignore:1:file* file1 .dvcignore:2:!file2 file2 -$ dvc check-ignore -d other + $ dvc check-ignore -d file* .dvcignore:1:file* file1 .dvcignore:2:!file2 file2 ``` -With the `--non-matching` option, non-matching `targets` will also be included -in the list. All fields in each line, except for ``, will be empty. +With the `--non-matching` (`-n`) option, non-matching `targets` will also be +included in the details list: ```dvc $ dvc check-ignore -d -n other diff --git a/content/docs/user-guide/dvcignore.md b/content/docs/user-guide/dvcignore.md index a9572b271e..f4ed136873 100644 --- a/content/docs/user-guide/dvcignore.md +++ b/content/docs/user-guide/dvcignore.md @@ -33,7 +33,7 @@ DVC-handled directories. they are not produced by a pipeline [stage](/doc/command-reference/run), they can be lost permanently. -Keep in mind, that when you add `.dvcignore` patterns that affect an existing +Keep in mind that when you add `.dvcignore` patterns that affect an existing output, its status will change and DVC will behave as if that affected files were deleted. From 8a6f121f8628cc02b0c5cceb7dc65c025a3381aa Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 7 Aug 2020 18:34:06 -0500 Subject: [PATCH 09/11] cmd: update check-ignore -n per https://github.com/iterative/dvc/pull/4323#discussion_r467325708 --- content/docs/command-reference/check-ignore.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/command-reference/check-ignore.md b/content/docs/command-reference/check-ignore.md index c4a2cb07a5..f47584fb53 100644 --- a/content/docs/command-reference/check-ignore.md +++ b/content/docs/command-reference/check-ignore.md @@ -23,11 +23,11 @@ ones that are ignored indeed are printed back. - `-d`, `--details` - show the exclude patterns along with each target path. A series of lines are printed in this format: - `:: | ` + `:: ` -- `-n`, `--non-matching` - show the target paths which don’t match any pattern - in a `--details` list. All fields in each line, except for ``, - will be empty. Has no effect without `--details`. +- `-n`, `--non-matching` - include the target paths which don’t match any + pattern in the `--details` list. All fields in each line, except for + ``, will be empty. Has no effect without `--details`. - `-h`, `--help` - prints the usage/help message, and exit. From 4332a29f57dab9956913f5aca619a45f8053ab36 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 7 Aug 2020 21:34:39 -0500 Subject: [PATCH 10/11] cmd: fix get.import -o descriptions per https://github.com/iterative/dvc.org/pull/1673#pullrequestreview-463533012 and https://github.com/iterative/dvc.org/pull/1673#pullrequestreview-463533118 --- content/docs/command-reference/get.md | 7 ++++--- content/docs/command-reference/import.md | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/content/docs/command-reference/get.md b/content/docs/command-reference/get.md index efcfc1d5f2..11270ec870 100644 --- a/content/docs/command-reference/get.md +++ b/content/docs/command-reference/get.md @@ -55,9 +55,10 @@ name. ## Options -- `-o `, `--out ` - specify a path to the desired location to place - the imported file in the workspace (instead of using the current working - directory). Directories specified in the path will be created by this command. +- `-o `, `--out ` - specify a path to the desired location in the + workspace to place the downloaded file or directory (instead of using the + current working directory). Directories specified in the path will be created + by this command. - `--rev ` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md index 2139e0ee24..459da12375 100644 --- a/content/docs/command-reference/import.md +++ b/content/docs/command-reference/import.md @@ -75,10 +75,10 @@ from the source repo. ## Options -- `-o `, `--out ` - specify a path to the desired location to place - the imported file in the workspace (instead of using the current working - directory). Directories specified in the path should already exist, otherwise - this command will fail. +- `-o `, `--out ` - specify a path to the desired location in the + workspace to place the downloaded file or directory (instead of using the + current working directory). Directories specified in the path should already + exist, otherwise this command will fail. - `--rev ` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to From 7d292e07b592544872f178a3714c71caf8445a2c Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sat, 8 Aug 2020 14:07:47 -0500 Subject: [PATCH 11/11] cmd: copy edits to remote add/modify --- content/docs/command-reference/remote/add.md | 42 +++++++++---------- .../docs/command-reference/remote/modify.md | 16 +++---- 2 files changed, 27 insertions(+), 31 deletions(-) diff --git a/content/docs/command-reference/remote/add.md b/content/docs/command-reference/remote/add.md index d4d83a5066..a585738f05 100644 --- a/content/docs/command-reference/remote/add.md +++ b/content/docs/command-reference/remote/add.md @@ -155,23 +155,22 @@ For more information about the variables DVC supports, please visit ### Click for Microsoft Azure Blob Storage ```dvc -$ dvc remote add --local myremote azure://my-container-name/path +$ dvc remote add -d myremote azure://my-container-name/path $ dvc remote modify --local myremote connection_string \ - "my-connection-string" + 'my-connection-string' ``` -> The connection string contains access to data and is inserted into the -> `.dvc/config` file. Therefore, it is safer to add the remote with the -> `--local` option, enforcing it to be written to a Git-ignored config file. See -> `dvc remote modify` for a full list of Azure storage parameters. +> The connection string contains sensitive user info. Therefore, it's safer to +> add it with the `--local` option, so it's written to a Git-ignored config +> file. See `dvc remote modify` for a full list of Azure storage parameters. The Azure Blob Storage remote can also be configured globally via environment variables: ```dvc -$ export AZURE_STORAGE_CONNECTION_STRING="" -$ export AZURE_STORAGE_CONTAINER_NAME="my-container-name" -$ dvc remote add -d myremote "azure://" +$ export AZURE_STORAGE_CONNECTION_STRING='' +$ export AZURE_STORAGE_CONTAINER_NAME='my-container-name' +$ dvc remote add -d myremote 'azure://' ``` > For more information on configuring Azure Storage connection strings, visit @@ -181,7 +180,7 @@ $ dvc remote add -d myremote "azure://" Storage Account. If you don't already have a storage account, you can create one following [these instructions](https://docs.microsoft.com/en-us/azure/storage/common/storage-create-storage-account). - The connection string can be found in the "Access Keys" pane of your Storage + The connection string can be found in the **Access Keys** pane of your Storage Account resource in the Azure portal. > 💡 Make sure the value is quoted so its processed correctly by the console. @@ -198,13 +197,12 @@ $ dvc remote add -d myremote "azure://" To start using a GDrive remote, first add it with a [valid URL format](/doc/user-guide/setup-google-drive-remote#url-format). Then -simply use any DVC command that needs it (e.g. `dvc pull`, `dvc fetch`, -`dvc push`), and follow the instructions to connect your Google Drive with DVC. -For example: +use any DVC command that needs to connect to it (e.g. `dvc pull` or `dvc push` +once there's tracked data to synchronize). For example: ```dvc $ dvc remote add -d myremote gdrive://0AIac4JZqHhKmUk9PDA/dvcstore -$ dvc push +$ dvc push # Assuming there's data to push Go to the following link in your browser: @@ -262,18 +260,18 @@ To set key id, key secret and endpoint (or any other OSS parameter), use option to avoid committing your secrets with Git: ```dvc +$ dvc remote modify myremote oss_endpoint $ dvc remote modify myremote --local oss_key_id my-key-id $ dvc remote modify myremote --local oss_key_secret my-key-secret -$ dvc remote modify myremote oss_endpoint endpoint ``` You can also set environment variables and use them later, to set environment variables use following environment variables: ```dvc -$ export OSS_ACCESS_KEY_ID="my-key-id" -$ export OSS_ACCESS_KEY_SECRET="my-key-secret" -$ export OSS_ENDPOINT="endpoint" +$ export OSS_ACCESS_KEY_ID='my-key-id' +$ export OSS_ACCESS_KEY_SECRET='my-key-secret' +$ export OSS_ENDPOINT='endpoint' ``` **Testing your OSS storage using docker** @@ -353,16 +351,14 @@ $ dvc remote add -d myremote webdavs://example.com/public.php/webdav > See also `dvc remote modify` for a full list of WebDAV parameters. -> Note that the location of the WebDAV API endpoint `/public.php/webdav` might -> be different for your server. -
### Click for local remote -A "local remote" is a directory in the machine's file system. +A "local remote" is a directory in the machine's file system. Not to be confused +with the `--local` option of `dvc remote` commands! > While the term may seem contradictory, it doesn't have to be. The "local" part > refers to the type of location where the storage is: another directory in the @@ -385,7 +381,7 @@ $ cat .dvc/config Using a relative path: ```dvc -$ dvc remote add myremote ../my-dvc-storage +$ dvc remote add -d myremote ../my-dvc-storage $ cat .dvc/config ... ['remote "myremote"'] diff --git a/content/docs/command-reference/remote/modify.md b/content/docs/command-reference/remote/modify.md index 4c1d862637..4c6ccdca0b 100644 --- a/content/docs/command-reference/remote/modify.md +++ b/content/docs/command-reference/remote/modify.md @@ -224,7 +224,7 @@ must explicitly set the `endpointurl` in the configuration: For example: ```dvc -$ dvc remote add myremote s3://path/to/dir +$ dvc remote add -d myremote s3://path/to/dir $ dvc remote modify myremote endpointurl \ https://object-storage.example.com ``` @@ -232,9 +232,9 @@ $ dvc remote modify myremote endpointurl \ S3 remotes can also be configured entirely via environment variables: ```dvc -$ export AWS_ACCESS_KEY_ID="" -$ export AWS_SECRET_ACCESS_KEY="" -$ dvc remote add myremote "s3://bucket/myremote" +$ export AWS_ACCESS_KEY_ID='' +$ export AWS_SECRET_ACCESS_KEY='' +$ dvc remote add -d myremote 's3://bucket/myremote' ``` For more information about the variables DVC supports, please visit @@ -249,14 +249,14 @@ For more information about the variables DVC supports, please visit - `url` - remote location URL. ```dvc - $ dvc remote modify myremote url "azure://my-container-name/path" + $ dvc remote modify myremote url 'azure://my-container-name/path' ``` - `connection_string` - connection string. ```dvc $ dvc remote modify --local myremote connection_string \ - "my-connection-string" + 'my-connection-string' ``` > The connection string contains sensitive user info. Therefore, it's safer to @@ -399,13 +399,13 @@ more information. ```dvc $ dvc remote modify \ - myremote credentialpath "/home/.../project-XXXXXXX.json" + myremote credentialpath '/home/.../project-XXXXXXX.json' ``` Alternatively, the `GOOGLE_APPLICATION_CREDENTIALS` env var can be set: ```dvc - $ export GOOGLE_APPLICATION_CREDENTIALS=".../project-XXXXXXX.json" + $ export GOOGLE_APPLICATION_CREDENTIALS='.../project-XXXXXXX.json' ```