From dca8ed2ea73ae5ac61b32222ce66401d23cd267e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 21 Feb 2020 18:48:59 -0600 Subject: [PATCH 01/12] get/import: update argument desc pero core repo --- public/static/docs/command-reference/get.md | 4 ++-- public/static/docs/command-reference/import.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md index 36ebc1fcba..4b55b4e091 100644 --- a/public/static/docs/command-reference/get.md +++ b/public/static/docs/command-reference/get.md @@ -12,8 +12,8 @@ directory. usage: dvc get [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path positional arguments: - url Location of DVC or Git repository to download from. - path Path to a file or directory within the repository. + url Location of DVC or Git repository to download from + path Path to a file or directory within the repository ``` ## Description diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md index b97bf79a57..e0dd38ef58 100644 --- a/public/static/docs/command-reference/import.md +++ b/public/static/docs/command-reference/import.md @@ -15,8 +15,8 @@ import. usage: dvc import [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path positional arguments: - url Location of DVC or Git repository to download from. - path Path to a file or directory within the repository. + url Location of DVC or Git repository to download from + path Path to a file or directory within the repository ``` ## Description From cd5b0dd033e8439dc4daa034741ef5ceb06c5165 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 24 Feb 2020 00:44:01 -0600 Subject: [PATCH 02/12] cmd ref: clarify what kind of workspace changes status displays per https://github.com/iterative/dvc.org/pull/953#pullrequestreview-363189334 --- public/static/docs/command-reference/status.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/public/static/docs/command-reference/status.md b/public/static/docs/command-reference/status.md index 6d16483660..d720ce632c 100644 --- a/public/static/docs/command-reference/status.md +++ b/public/static/docs/command-reference/status.md @@ -19,11 +19,12 @@ positional arguments: ## Description `dvc status` searches for changes in the existing pipelines, either showing -which [stages](/doc/command-reference/run) have changed in the workspace -(including uncommitted local changes) and must be reproduced (with `dvc repro`), -or differences between cache vs. remote storage (meaning `dvc push` -or `dvc pull` should be run to synchronize them). The two modes, _local_ and -_cloud_ are triggered by using the `--cloud` or `--remote` options: +which [stages](/doc/command-reference/run) have changed in the workspace (not +yet tracked by DVC) and must be added again (with `dvc add`) or reproduced (with +`dvc repro`); or differences between cache vs. remote storage +(meaning `dvc push` or `dvc pull` should be run to synchronize them). The two +modes, _local_ and _cloud_ are triggered by using the `--cloud` or `--remote` +options: | Mode | CLI Option | Description | | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- | From bf340aa7973204fbb1c58b042dc3704707e574bb Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 27 Feb 2020 18:13:02 -0600 Subject: [PATCH 03/12] tutorials: remove unnecessary remove cmd from versioning tut --- public/static/docs/tutorials/versioning.md | 1 - 1 file changed, 1 deletion(-) diff --git a/public/static/docs/tutorials/versioning.md b/public/static/docs/tutorials/versioning.md index c08dd8f9c6..12e4de36c3 100644 --- a/public/static/docs/tutorials/versioning.md +++ b/public/static/docs/tutorials/versioning.md @@ -317,7 +317,6 @@ When you have a script that takes some data as an input and produces other data > ``` ```dvc -$ dvc remove -pf model.h5.dvc $ dvc run -f Dvcfile \ -d train.py -d data \ -M metrics.csv \ From 2c3452119545987f77b764e4aa6fc94d051092a7 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 28 Feb 2020 00:50:18 -0600 Subject: [PATCH 04/12] cmd ref: update and wrap metrics diff synopsis --- public/static/docs/command-reference/metrics/show.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md index 919828c3ac..f5226c417e 100644 --- a/public/static/docs/command-reference/metrics/show.md +++ b/public/static/docs/command-reference/metrics/show.md @@ -6,12 +6,12 @@ formatting. ## Synopsis ```usage -usage: dvc metrics show [-h] [-q | -v] [-t TYPE] [-x XPATH] [-a] [-T] [-R] +usage: dvc metrics show [-h] [-q | -v] + [-t TYPE] [-x XPATH] [-a] [-T] [-R] [targets [targets ...]] positional arguments: - targets Metric files or directories (see -R) to show (leave - empty to display all) + targets Metric files or directories (see -R) to show ``` ## Description From b14c5fbe7162f875ab8e2e598f42e2f54f64c918 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Tue, 3 Mar 2020 23:58:33 -0600 Subject: [PATCH 05/12] use-cases: typo in shared dev case --- public/static/docs/use-cases/shared-development-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/static/docs/use-cases/shared-development-server.md b/public/static/docs/use-cases/shared-development-server.md index f1c357c779..a96a19150a 100644 --- a/public/static/docs/use-cases/shared-development-server.md +++ b/public/static/docs/use-cases/shared-development-server.md @@ -38,7 +38,7 @@ $ mv .dvc/cache/* /path/to/dvc-cache ``` Now you need to ensure that cache files/directories have appropriate -permissions, so that they could be accessed by your collegues that are members +permissions, so that they could be accessed by your colleagues that are members of the same group: ```dvc From bc43303cd7677440caa72be7712bc618f6505e0e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 9 Mar 2020 16:35:08 -0600 Subject: [PATCH 06/12] cmd ref: improve and standardize paragraph about dvc init creating .dvc/ per https://github.com/iterative/dvc.org/pull/1022#pullrequestreview-371480713 --- public/static/docs/command-reference/cache/index.md | 5 +++-- public/static/docs/command-reference/init.md | 9 ++++----- public/static/docs/get-started/initialize.md | 9 ++++----- public/static/docs/tutorials/deep/preparation.md | 11 +++++------ public/static/docs/tutorials/pipelines.md | 9 ++++----- .../docs/use-cases/versioning-data-and-model-files.md | 8 ++++---- 6 files changed, 24 insertions(+), 27 deletions(-) diff --git a/public/static/docs/command-reference/cache/index.md b/public/static/docs/command-reference/cache/index.md index 2ac04dc3ab..f0bacf75a9 100644 --- a/public/static/docs/command-reference/cache/index.md +++ b/public/static/docs/command-reference/cache/index.md @@ -15,8 +15,9 @@ positional arguments: ## Description -After DVC initialization, a hidden directory `.dvc/` is created to contain the -[DVC files and directories](/doc/user-guide/dvc-files-and-directories), +At DVC initialization, a new `.dvc/` directory will be created with the +`config`, `.gitignore`, among +[other files and directories](/doc/user-guide/dvc-files-and-directories), including the default cache directory. The cache is where your data files, models, etc (anything you want to version diff --git a/public/static/docs/command-reference/init.md b/public/static/docs/command-reference/init.md index 13dd336cf4..903f2efdfe 100644 --- a/public/static/docs/command-reference/init.md +++ b/public/static/docs/command-reference/init.md @@ -22,11 +22,10 @@ scenarios like monorepos, automation, etc: - [Initializing DVC without Git](#how-does-it-affect-dvc-commands) - support for SCM other than Git, deployment automation cases, etc. -After DVC initialization, a new directory `.dvc/` will be created with the -`config` and `.gitignore` files. These and other files and directories are -hidden from user, as typically there's no need to interact with them directly. -See [DVC Files and Directories](/doc/user-guide/dvc-files-and-directories) to -learn more. +At DVC initialization, a new `.dvc/` directory will be created with the +`config`, `.gitignore`, among +[other files and directories](/doc/user-guide/dvc-files-and-directories) that +are hidden from the user. ### Initializing DVC in subdirectories diff --git a/public/static/docs/get-started/initialize.md b/public/static/docs/get-started/initialize.md index 3c20aabeb4..4570ca7a2c 100644 --- a/public/static/docs/get-started/initialize.md +++ b/public/static/docs/get-started/initialize.md @@ -15,11 +15,10 @@ $ dvc init $ git commit -m "Initialize DVC project" ``` -After DVC initialization, a new directory `.dvc/` will be created with the -`config` and `.gitignore` files. These and other files and directories are -hidden from user, as typically there's no need to interact with them directly. -See [DVC Files and Directories](/doc/user-guide/dvc-files-and-directories) to -learn more. +At DVC initialization, a new `.dvc/` directory will be created with the +`config`, `.gitignore`, among +[other files and directories](/doc/user-guide/dvc-files-and-directories) that +are hidden from the user. > See `dvc init` if you want to get more details about the initialization > process, and diff --git a/public/static/docs/tutorials/deep/preparation.md b/public/static/docs/tutorials/deep/preparation.md index b2c9f6c321..0941923a07 100644 --- a/public/static/docs/tutorials/deep/preparation.md +++ b/public/static/docs/tutorials/deep/preparation.md @@ -61,12 +61,11 @@ $ pip install -r code/requirements.txt DVC works on top of Git repositories. You run DVC initialization in a repository directory to create DVC meta files and directories. -After DVC initialization, a new directory `.dvc/` will be created with the -`config` and `.gitignore` files. These and other files and directories are -hidden from user, as typically there's no need to interact with them directly. -See [DVC Files and Directories](/doc/user-guide/dvc-files-and-directories) to -learn more. However, we describe some DVC internals below for a better -understanding of how it works. +At DVC initialization, a new `.dvc/` directory will be created with the +`config`, `.gitignore`, among +[other files and directories](/doc/user-guide/dvc-files-and-directories) that +are hidden from the user. However, we describe some DVC internals below for a +better understanding of how it works. ```dvc $ dvc init diff --git a/public/static/docs/tutorials/pipelines.md b/public/static/docs/tutorials/pipelines.md index 1660f089eb..c54d6e34ef 100644 --- a/public/static/docs/tutorials/pipelines.md +++ b/public/static/docs/tutorials/pipelines.md @@ -101,11 +101,10 @@ When we run `dvc add` `Posts.xml.zip`, DVC creates a ### Expand to learn about DVC internals -`dvc init` created a new directory `.dvc/`, with the `config` and `.gitignore` -files. These and other files and directories are hidden from user, as typically -there's no need to interact with them directly. See -[DVC Files and Directories](/doc/user-guide/dvc-files-and-directories) to learn -more. +At DVC initialization, a new `.dvc/` directory will be created with the +`config`, `.gitignore`, among +[other files and directories](/doc/user-guide/dvc-files-and-directories) that +are hidden from the user. Note that the DVC-file created by `dvc add` has no dependencies, a.k.a. an _orphan_ [stage file](/doc/command-reference/run): diff --git a/public/static/docs/use-cases/versioning-data-and-model-files.md b/public/static/docs/use-cases/versioning-data-and-model-files.md index 1ff68d03a3..a31d82cc81 100644 --- a/public/static/docs/use-cases/versioning-data-and-model-files.md +++ b/public/static/docs/use-cases/versioning-data-and-model-files.md @@ -42,10 +42,10 @@ initialize the DVC project on top of the existing repository: $ dvc init ``` -DVC creates a `.dvc/` directory that stores -[internals](/doc/user-guide/dvc-files-and-directories), including the -`.dvc/cache` directory (local data storage). These can safely be tracked with -Git: +At DVC initialization, a new `.dvc/` directory will be created with DVC +[internal files and directories](/doc/user-guide/dvc-files-and-directories), +including the `.dvc/cache` directory (local data storage). These can safely be +tracked with Git: ```dvc $ git status From df7527f68d4265a6919564d6d704d479b6dd8ad4 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Tue, 10 Mar 2020 14:01:39 -0600 Subject: [PATCH 07/12] typo --- public/static/docs/command-reference/repro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md index 77bf692cfa..af34d281ed 100644 --- a/public/static/docs/command-reference/repro.md +++ b/public/static/docs/command-reference/repro.md @@ -149,7 +149,7 @@ and only execute the final stage. - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if all stages are up to date or if all stages are successfully executed, otherwise exit with 1. The command defined in the stage is free to write output - irregardless of this flag. + regardless of this flag. - `-v`, `--verbose` - displays detailed tracing information. From 9b04fc92cf3d31daa015a70b31627266d39069e2 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Tue, 10 Mar 2020 15:17:18 -0500 Subject: [PATCH 08/12] cmd ref: term options -> values in cmd arg synopsis... needs similar patch in core repo. --- public/static/docs/command-reference/metrics/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/static/docs/command-reference/metrics/index.md b/public/static/docs/command-reference/metrics/index.md index 4abc570c91..a6eae1f3a0 100644 --- a/public/static/docs/command-reference/metrics/index.md +++ b/public/static/docs/command-reference/metrics/index.md @@ -16,7 +16,7 @@ positional arguments: COMMAND show Output metric values. add Tag file as a metric file. - modify Modify metric file options. + modify Modify metric file values. remove Remove files's metric tag. ``` From e96b22e5299a80c9b300aadc0b0c175b4672050e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Mar 2020 11:41:35 -0600 Subject: [PATCH 09/12] api ref: update metrics docs to use phrase "formatting" instead of "options" per https://github.com/iterative/dvc/pull/3471#pullrequestreview-372934577 --- .../docs/command-reference/metrics/add.md | 17 +++++++++-------- .../docs/command-reference/metrics/diff.md | 2 +- .../docs/command-reference/metrics/index.md | 2 +- .../docs/command-reference/metrics/modify.md | 17 ++++++++--------- .../docs/command-reference/metrics/remove.md | 8 ++++---- .../docs/command-reference/metrics/show.md | 8 ++++---- 6 files changed, 27 insertions(+), 27 deletions(-) diff --git a/public/static/docs/command-reference/metrics/add.md b/public/static/docs/command-reference/metrics/add.md index 8b571b5a3e..78cbba7c10 100644 --- a/public/static/docs/command-reference/metrics/add.md +++ b/public/static/docs/command-reference/metrics/add.md @@ -1,6 +1,7 @@ # metrics add -Mark the file located at `path` as a metric file. +Mark output file as a +[project metric](/doc/command-reference/metrics). ## Synopsis @@ -14,25 +15,25 @@ positional arguments: ## Description Sets the `metric` field in the [DVC-file](/doc/user-guide/dvc-file-format) that -defines the given `path` as an output, marking `path` as a -[project metric](/doc/command-reference/metrics) to track. +defines the given `path` as an output, marking `path` as a metric +file to track. Note that outputs can also be marked as metrics via the `-m` or `-M` options of the `dvc run` command. While any text file can be tracked as a metric file, we recommend using TSV, CSV, or JSON formats. DVC provides a way to parse those formats to get to a -specific value, if the file contains multiple metrics. See `dvc metrics show` -for more details. +specific value, if the file contains multiple metrics. See the +[options](#options) below and `dvc metrics show` for more info. > Note that [external output](/doc/user-guide/managing-external-data) cannot be > marked as project metrics. ## Options -- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw` - (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the - corresponding DVC-file, and used by `dvc metrics show` to determine how to +- `-t`, `--type` - specify a type for the metric file. Accepted values are: + `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into + the corresponding DVC-file, and used by `dvc metrics show` to determine how to handle displaying metrics. `raw` means that no additional parsing is applied, and `--xpath` is ignored. diff --git a/public/static/docs/command-reference/metrics/diff.md b/public/static/docs/command-reference/metrics/diff.md index 0b60a70116..0096c5c6e9 100644 --- a/public/static/docs/command-reference/metrics/diff.md +++ b/public/static/docs/command-reference/metrics/diff.md @@ -1,6 +1,6 @@ # metrics diff -Show changes in [metrics](/doc/command-reference/metrics#description) between +Show changes in [project metrics](/doc/command-reference/metrics), between commits in the DVC repository, or between a commit and the workspace. diff --git a/public/static/docs/command-reference/metrics/index.md b/public/static/docs/command-reference/metrics/index.md index a6eae1f3a0..062660cdd7 100644 --- a/public/static/docs/command-reference/metrics/index.md +++ b/public/static/docs/command-reference/metrics/index.md @@ -1,6 +1,6 @@ # metrics -A set of commands to collect and display project metrics: +A set of commands to add, manage, collect, and display project metrics: [add](/doc/command-reference/metrics/add), [show](/doc/command-reference/metrics/show), [diff](/doc/command-reference/metrics/diff), diff --git a/public/static/docs/command-reference/metrics/modify.md b/public/static/docs/command-reference/metrics/modify.md index dcd5fb657d..26792056df 100644 --- a/public/static/docs/command-reference/metrics/modify.md +++ b/public/static/docs/command-reference/metrics/modify.md @@ -1,7 +1,7 @@ # metrics modify -Modify [project metric](/doc/command-reference/metrics) values such as type, -path expression that is used to parse it, etc. (See full options below.) +Modify [project metric](/doc/command-reference/metrics) default formatting with +options such as `type` or `xpath`. See full [options](#options) info below. ## Synopsis @@ -15,10 +15,9 @@ positional arguments: ## Description This command finds a corresponding [DVC-file](/doc/user-guide/dvc-file-format) -for the provided metric file `path` – the one that defines `path` among its -outputs, see `dvc metrics add` or the `-m` and `-M` options of -`dvc run` – and updates the specification of the metric. (See full options -below.) +for the provided metric file (`path` is defined among the outputs +of the DVC-file), and updates the default formatting of the metric. (See the +[options](#options) below and `dvc metrics show` for more info.) If `path` isn't tracked by DVC (described in one of the workspace DVC-files), the following error will be raised: @@ -33,9 +32,9 @@ ERROR: failed to modify metric file settings - ## Options -- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw` - (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the - corresponding DVC-file, and used by `dvc metrics show` to determine how to +- `-t`, `--type` - specify a type for the metric file. Accepted values are: + `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into + the corresponding DVC-file, and used by `dvc metrics show` to determine how to handle displaying metrics. `raw` means that no additional parsing is applied, and `--xpath` is ignored. diff --git a/public/static/docs/command-reference/metrics/remove.md b/public/static/docs/command-reference/metrics/remove.md index 79be43f69c..bbb6f77e95 100644 --- a/public/static/docs/command-reference/metrics/remove.md +++ b/public/static/docs/command-reference/metrics/remove.md @@ -1,7 +1,8 @@ # metrics remove Stop tracking a [project metric](/doc/command-reference/metrics): Keeps file -located at `path` an output, but removes its metric mark. +located at `path` as an output, but removes its metric mark in the +DVC-file. ## Synopsis @@ -16,9 +17,8 @@ positional arguments: ## Description This command finds a corresponding [DVC-file](/doc/user-guide/dvc-file-format) -for the provided metric file `path` – the one that defines `path` among its -outputs, see `dvc metrics add` or the `-m` and `-M` options of -`dvc run` – and resets the `metric` field for the provided output. +for the provided metric file (`path` is defined among the outputs +of the DVC-file), and resets the `metric` field for the file. This does not remove or delete the file in question. It only unmarks it as a metric file. It also keeps the file as an output of the corresponding DVC-file. diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md index 8532c30571..f4f67fe79e 100644 --- a/public/static/docs/command-reference/metrics/show.md +++ b/public/static/docs/command-reference/metrics/show.md @@ -1,6 +1,6 @@ # metrics show -Find and print [project metrics](/doc/command-reference/metrics), with optional +Print [project metrics](/doc/command-reference/metrics), with optional formatting. ## Synopsis @@ -43,9 +43,9 @@ compares them with a previous version. ## Options -- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw` - (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to determine - how to parse and format metics for display. +- `-t`, `--type` - specify a type for the metric file. Accepted values are: + `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to + determine how to parse and format metics for display. `raw` means that no additional parsing is applied, and `--xpath` is ignored. `htsv`/`hcsv` are the same as `tsv`/`csv`, but the values in the first row of From 7305171b2255e3406d05c47aca2753e269eeafbb Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Mar 2020 12:10:35 -0600 Subject: [PATCH 10/12] remove term rsync per #1026 --- src/components/Diagram/index.js | 2 +- src/components/Features/index.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/components/Diagram/index.js b/src/components/Diagram/index.js index cd97d6e87e..6148dc1338 100644 --- a/src/components/Diagram/index.js +++ b/src/components/Diagram/index.js @@ -51,7 +51,7 @@ const ColumnOne = () => ( Version control machine learning models, data sets and intermediate files. DVC connects them with code, and uses Amazon S3, Microsoft Azure Blob Storage, Google Drive, Google Cloud Storage, Aliyun OSS, SSH/SFTP, - HDFS, HTTP, network-attached storage, or rsync to store file contents. + HDFS, HTTP, network-attached storage, or disc to store file contents.

Full code and data provenance help track the complete evolution of every diff --git a/src/components/Features/index.js b/src/components/Features/index.js index e6f5221824..316d695c96 100644 --- a/src/components/Features/index.js +++ b/src/components/Features/index.js @@ -43,7 +43,7 @@ export default function FeaturesPage() { Use Amazon S3, Microsoft Azure Blob Storage, Google Drive, Google Cloud Storage, Aliyun OSS, SSH/SFTP, HDFS, HTTP, network-attached - storage, or rsync to store data. The list of supported remote + storage, or disc to store data. The list of supported remote storage is constantly expanding. From f1ed6f0239c945bcf127c51d3df846d90de44bea Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Mar 2020 19:14:04 -0600 Subject: [PATCH 11/12] cmd ref: use infinitive in short intros, simple present in Descriptions --- public/static/docs/command-reference/fetch.md | 21 +++++++++---------- public/static/docs/command-reference/move.md | 4 ++-- .../docs/command-reference/pipeline/list.md | 3 +-- public/static/docs/command-reference/pull.md | 12 +++++------ public/static/docs/command-reference/push.md | 8 +++---- .../docs/command-reference/remote/default.md | 2 +- .../docs/command-reference/remote/list.md | 2 +- .../docs/command-reference/remote/modify.md | 2 +- .../docs/command-reference/remote/remove.md | 4 ++-- public/static/docs/command-reference/repro.md | 2 +- public/static/docs/command-reference/root.md | 2 +- .../docs/command-reference/unprotect.md | 2 +- .../static/docs/command-reference/version.md | 6 ++---- 13 files changed, 33 insertions(+), 37 deletions(-) diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md index 7c4e9de196..c62523adf8 100644 --- a/public/static/docs/command-reference/fetch.md +++ b/public/static/docs/command-reference/fetch.md @@ -1,6 +1,6 @@ # fetch -Get files or directories tracked by DVC from +Get tracked files or directories from [remote storage](/doc/command-reference/remote) into the cache. ## Synopsis @@ -17,12 +17,11 @@ positional arguments: ## Description -The `dvc fetch` command is a means to download files from remote storage into -the cache of the project, but without placing them in the -workspace. This makes the data files available for linking (or -copying) into the workspace. (Refer to -[dvc config cache.type](/doc/command-reference/config#cache).) Along with -`dvc checkout`, it's performed automatically by `dvc pull` when the target +The `dvc fetch` downloads DVC-tracked files from remote storage into the cache +of the project, but without placing them in the workspace. This +makes the data files available for linking (or copying) into the workspace. +(Refer to [dvc config cache.type](/doc/command-reference/config#cache).) Along +with `dvc checkout`, it's performed automatically by `dvc pull` when the target [DVC-files](/doc/user-guide/dvc-file-format) are not already in the cache: ``` @@ -44,10 +43,10 @@ project's cache ++ | dvc pull | Fetching could be useful when first checking out a DVC project, since files tracked by DVC should already exist in remote storage, but won't be -in the project's cache. (Refer to `dvc remote` for more information on DVC -remotes.) These necessary data or model files are listed as dependencies or -outputs in a DVC-file (target [stage](/doc/command-reference/run)) so they are -required to [reproduce](/doc/get-started/reproduce) the corresponding +in the project's cache. (Refer to `dvc remote` for more information +on DVC remotes.) These necessary data or model files are listed as dependencies +or outputs in a DVC-file (target [stage](/doc/command-reference/run)) so they +are required to [reproduce](/doc/get-started/reproduce) the corresponding [pipeline](/doc/command-reference/pipeline). (See [DVC-File Format](/doc/user-guide/dvc-file-format) for more information on dependencies and outputs.) diff --git a/public/static/docs/command-reference/move.md b/public/static/docs/command-reference/move.md index 3cdf71754d..7b8c63411d 100644 --- a/public/static/docs/command-reference/move.md +++ b/public/static/docs/command-reference/move.md @@ -1,9 +1,9 @@ # move -Renames a file or a directory and modifies the corresponding +Rename a file or a directory and modify the corresponding [DVC-file](/doc/user-guide/dvc-file-format) (see `dvc add`) to reflect the change. If the file or directory has the same name as the corresponding -DVC-file, it would also rename the DVC-file. +DVC-file, it also renames it. ## Synopsis diff --git a/public/static/docs/command-reference/pipeline/list.md b/public/static/docs/command-reference/pipeline/list.md index 6a70d2e261..8772437424 100644 --- a/public/static/docs/command-reference/pipeline/list.md +++ b/public/static/docs/command-reference/pipeline/list.md @@ -1,7 +1,6 @@ # pipeline list -Show connected groups (pipelines) of [stage](/doc/command-reference/run) that -are independent of each other. +List connected groups of [stages](/doc/command-reference/run) (pipelines). ## Synopsis diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md index 1702ba6717..ea7aec8d7d 100644 --- a/public/static/docs/command-reference/pull.md +++ b/public/static/docs/command-reference/pull.md @@ -1,9 +1,9 @@ # pull -Downloads missing files and directories from -[remote storage](/doc/command-reference/remote) to the cache based -on [DVC-files](/doc/user-guide/dvc-file-format) in the workspace, -then links the downloaded files into the workspace. +Download tracked files or directories from +[remote storage](/doc/command-reference/remote) to the cache and +workspace, based on the current +[DVC-files](/doc/user-guide/dvc-file-format). ## Synopsis @@ -20,8 +20,8 @@ positional arguments: ## Description The `dvc pull` and `dvc push` commands are the means for uploading and -downloading data to and from remote storage. These commands are analogous to the -`git pull` and `git push` commands. +downloading data to and from remote storage. These commands are analogous to +`git pull` and `git push`, respectively. [Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments and preserving data versions (input datasets, intermediate results, models, [metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.) diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md index d736486ef5..6a550faaea 100644 --- a/public/static/docs/command-reference/push.md +++ b/public/static/docs/command-reference/push.md @@ -1,6 +1,6 @@ # push -Uploads files or directories tracked by DVC to +Upload tracked files or directories to [remote storage](/doc/command-reference/remote). ## Synopsis @@ -17,9 +17,9 @@ positional arguments: ## Description -The `dvc push` command is the twin pair to the `dvc pull` command, and together -they are the means for uploading and downloading data to and from remote -storage, respectively. +The `dvc pull` and `dvc push` commands are the means for uploading and +downloading data to and from remote storage. These commands are analogous to +`git pull` and `git push`, respectively. [Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments and preserving data versions (input datasets, intermediate results, models, [metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.) diff --git a/public/static/docs/command-reference/remote/default.md b/public/static/docs/command-reference/remote/default.md index 9e5f5aa895..41a9cb8b4e 100644 --- a/public/static/docs/command-reference/remote/default.md +++ b/public/static/docs/command-reference/remote/default.md @@ -1,6 +1,6 @@ # remote default -Set/unset a default data remote. +Set/unset the default data remote. > Depending on your remote storage type, you may also need `dvc remote modify` > to provide credentials and/or configure other remote parameters. diff --git a/public/static/docs/command-reference/remote/list.md b/public/static/docs/command-reference/remote/list.md index fa01afee72..57b39278cb 100644 --- a/public/static/docs/command-reference/remote/list.md +++ b/public/static/docs/command-reference/remote/list.md @@ -1,6 +1,6 @@ # remote list -Show all available data remotes. +List all available data remotes. See also [add](/doc/command-reference/remote/add), [default](/doc/command-reference/remote/default), diff --git a/public/static/docs/command-reference/remote/modify.md b/public/static/docs/command-reference/remote/modify.md index f87e65c858..5ac6f7d55f 100644 --- a/public/static/docs/command-reference/remote/modify.md +++ b/public/static/docs/command-reference/remote/modify.md @@ -1,6 +1,6 @@ # remote modify -Modify configuration of data remotes. +Modify the configuration of a data remote. > This command is commonly needed after `dvc remote add` or > [default](/doc/command-reference/remote/default) to setup credentials or other diff --git a/public/static/docs/command-reference/remote/remove.md b/public/static/docs/command-reference/remote/remove.md index d69028876b..087ef09fc8 100644 --- a/public/static/docs/command-reference/remote/remove.md +++ b/public/static/docs/command-reference/remote/remove.md @@ -1,7 +1,7 @@ # remote remove -Remove a data remotes. This command affects DVC configuration files only, it -does not physically remove data files stored remotely. +Remove a data remote. This command affects DVC configuration files only, it does +not physically remove data files stored remotely. See also [add](/doc/command-reference/remote/add), [default](/doc/command-reference/remote/default), diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md index af34d281ed..e2d6b32897 100644 --- a/public/static/docs/command-reference/repro.md +++ b/public/static/docs/command-reference/repro.md @@ -1,7 +1,7 @@ # repro Reproduce complete or partial [pipelines](/doc/command-reference/pipeline) by -executing commands defined in their [stages](/doc/command-reference/run), in the +executing commands defined in their [stages](/doc/command-reference/run) in the correct order. The commands to be executed are determined by recursively analyzing dependencies and outputs of the target stages. diff --git a/public/static/docs/command-reference/root.md b/public/static/docs/command-reference/root.md index 22ec39b3b5..04454a16ac 100644 --- a/public/static/docs/command-reference/root.md +++ b/public/static/docs/command-reference/root.md @@ -1,6 +1,6 @@ # root -Returns relative path to the DVC project. +Return the relative path to the DVC project. ## Synopsis diff --git a/public/static/docs/command-reference/unprotect.md b/public/static/docs/command-reference/unprotect.md index 122e2ec90d..e59c94355a 100644 --- a/public/static/docs/command-reference/unprotect.md +++ b/public/static/docs/command-reference/unprotect.md @@ -14,7 +14,7 @@ positional arguments: ## Description -By default this command is not necessary, as DVC avoids hardlinks and symlinks +By default, this command is not necessary, as DVC avoids hardlinks and symlinks to link tracked data files from the cache to the workspace. However, these types of file links can be enabled with `dvc config cache` (`cache.type` config option). diff --git a/public/static/docs/command-reference/version.md b/public/static/docs/command-reference/version.md index 0e4d94c299..622920faa2 100644 --- a/public/static/docs/command-reference/version.md +++ b/public/static/docs/command-reference/version.md @@ -1,7 +1,6 @@ # version -This command shows the system/environment information along with the DVC -version. +Display the DVC version along with the system/environment information. ## Synopsis @@ -11,8 +10,7 @@ usage: dvc version [-h] [-q | -v] ## Description -Running the command `dvc version` outputs the following information about the -system/environment: +`dvc version` outputs the following information about the system/environment: | Line | Detail | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | From f17ed4872875f11ce1aa38e5f4004925fbfcc2df Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Mar 2020 19:33:43 -0600 Subject: [PATCH 12/12] cmd ref: rephrase paragraph about DVC internals per https://github.com/iterative/dvc.org/pull/1014#pullrequestreview-372364462 --- public/static/docs/command-reference/cache/index.md | 8 ++++---- public/static/docs/command-reference/init.md | 8 ++++---- public/static/docs/get-started/initialize.md | 8 ++++---- public/static/docs/tutorials/deep/preparation.md | 10 +++++----- public/static/docs/tutorials/pipelines.md | 8 ++++---- .../docs/use-cases/versioning-data-and-model-files.md | 8 ++++---- 6 files changed, 25 insertions(+), 25 deletions(-) diff --git a/public/static/docs/command-reference/cache/index.md b/public/static/docs/command-reference/cache/index.md index f0bacf75a9..fb802105d4 100644 --- a/public/static/docs/command-reference/cache/index.md +++ b/public/static/docs/command-reference/cache/index.md @@ -15,10 +15,10 @@ positional arguments: ## Description -At DVC initialization, a new `.dvc/` directory will be created with the -`config`, `.gitignore`, among -[other files and directories](/doc/user-guide/dvc-files-and-directories), -including the default cache directory. +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. The cache is where your data files, models, etc (anything you want to version with DVC) are actually stored. The corresponding files you see in the diff --git a/public/static/docs/command-reference/init.md b/public/static/docs/command-reference/init.md index 903f2efdfe..3c8316ff7a 100644 --- a/public/static/docs/command-reference/init.md +++ b/public/static/docs/command-reference/init.md @@ -22,10 +22,10 @@ scenarios like monorepos, automation, etc: - [Initializing DVC without Git](#how-does-it-affect-dvc-commands) - support for SCM other than Git, deployment automation cases, etc. -At DVC initialization, a new `.dvc/` directory will be created with the -`config`, `.gitignore`, among -[other files and directories](/doc/user-guide/dvc-files-and-directories) that -are hidden from the user. +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. ### Initializing DVC in subdirectories diff --git a/public/static/docs/get-started/initialize.md b/public/static/docs/get-started/initialize.md index 4570ca7a2c..23a8335ae1 100644 --- a/public/static/docs/get-started/initialize.md +++ b/public/static/docs/get-started/initialize.md @@ -15,10 +15,10 @@ $ dvc init $ git commit -m "Initialize DVC project" ``` -At DVC initialization, a new `.dvc/` directory will be created with the -`config`, `.gitignore`, among -[other files and directories](/doc/user-guide/dvc-files-and-directories) that -are hidden from the user. +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. > See `dvc init` if you want to get more details about the initialization > process, and diff --git a/public/static/docs/tutorials/deep/preparation.md b/public/static/docs/tutorials/deep/preparation.md index 0941923a07..6db7335400 100644 --- a/public/static/docs/tutorials/deep/preparation.md +++ b/public/static/docs/tutorials/deep/preparation.md @@ -61,11 +61,11 @@ $ pip install -r code/requirements.txt DVC works on top of Git repositories. You run DVC initialization in a repository directory to create DVC meta files and directories. -At DVC initialization, a new `.dvc/` directory will be created with the -`config`, `.gitignore`, among -[other files and directories](/doc/user-guide/dvc-files-and-directories) that -are hidden from the user. However, we describe some DVC internals below for a -better understanding of how it works. +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. We describe some DVC internals below for a better +understanding of how it works. ```dvc $ dvc init diff --git a/public/static/docs/tutorials/pipelines.md b/public/static/docs/tutorials/pipelines.md index c54d6e34ef..35964ebd2e 100644 --- a/public/static/docs/tutorials/pipelines.md +++ b/public/static/docs/tutorials/pipelines.md @@ -101,10 +101,10 @@ When we run `dvc add` `Posts.xml.zip`, DVC creates a ### Expand to learn about DVC internals -At DVC initialization, a new `.dvc/` directory will be created with the -`config`, `.gitignore`, among -[other files and directories](/doc/user-guide/dvc-files-and-directories) that -are hidden from the user. +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. Note that the DVC-file created by `dvc add` has no dependencies, a.k.a. an _orphan_ [stage file](/doc/command-reference/run): diff --git a/public/static/docs/use-cases/versioning-data-and-model-files.md b/public/static/docs/use-cases/versioning-data-and-model-files.md index a31d82cc81..8c4c3b4e29 100644 --- a/public/static/docs/use-cases/versioning-data-and-model-files.md +++ b/public/static/docs/use-cases/versioning-data-and-model-files.md @@ -42,10 +42,10 @@ initialize the DVC project on top of the existing repository: $ dvc init ``` -At DVC initialization, a new `.dvc/` directory will be created with DVC -[internal files and directories](/doc/user-guide/dvc-files-and-directories), -including the `.dvc/cache` directory (local data storage). These can safely be -tracked with Git: +At DVC initialization, a new `.dvc/` directory will be created for internal +configuration and cache +[files and directories](/doc/user-guide/dvc-files-and-directories) that are +hidden from the user. These can safely be tracked with Git: ```dvc $ git status