From 499d382bae1c65d32df4b66106d56840a00a9bdd Mon Sep 17 00:00:00 2001 From: Ivan Shcheklein Date: Thu, 27 Feb 2020 14:51:55 -0800 Subject: [PATCH 1/2] Update versioning.md --- public/static/docs/tutorials/versioning.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/public/static/docs/tutorials/versioning.md b/public/static/docs/tutorials/versioning.md index c513fb9e88..c08dd8f9c6 100644 --- a/public/static/docs/tutorials/versioning.md +++ b/public/static/docs/tutorials/versioning.md @@ -229,10 +229,6 @@ $ python train.py $ dvc add model.h5 ``` -> `dvc remove` is necessary here because `model.h5` was already added with -> `dvc add` earlier, but we want to do so again. Later we'll see how `dvc run` -> eliminates this extra step. - Let's commit the second version: ```dvc From 96b37a3a501583467d31f1de25f512d8ded62812 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 27 Feb 2020 18:34:02 -0600 Subject: [PATCH 2/2] cmd ref: review option defaults and sentence priority per API params (#1027) * cmd ref: review explanation of option defaults per https://github.com/iterative/dvc.org/pull/908#pullrequestreview-356423629 * cmd ref: change language on option requirements (from "effect" to "ignored") per https://github.com/iterative/dvc.org/pull/908#pullrequestreview-356423672 --- public/static/docs/command-reference/add.md | 15 ++++--- .../static/docs/command-reference/checkout.md | 19 +++++---- .../static/docs/command-reference/commit.md | 18 ++++----- .../static/docs/command-reference/config.md | 32 +++++++-------- public/static/docs/command-reference/fetch.md | 32 +++++++-------- public/static/docs/command-reference/gc.md | 4 +- public/static/docs/command-reference/get.md | 13 +++---- .../docs/command-reference/import-url.md | 9 ++--- .../static/docs/command-reference/import.md | 7 ++-- .../docs/command-reference/metrics/diff.md | 8 ++-- .../docs/command-reference/metrics/show.md | 4 +- public/static/docs/command-reference/pull.md | 32 +++++++-------- public/static/docs/command-reference/push.md | 34 ++++++++-------- .../docs/command-reference/remote/add.md | 2 +- .../static/docs/command-reference/remove.md | 4 +- public/static/docs/command-reference/repro.md | 8 ++-- public/static/docs/command-reference/run.md | 39 +++++++++---------- .../static/docs/command-reference/status.md | 17 ++++---- 18 files changed, 143 insertions(+), 154 deletions(-) diff --git a/public/static/docs/command-reference/add.md b/public/static/docs/command-reference/add.md index e3f37bb09f..b7a68fb348 100644 --- a/public/static/docs/command-reference/add.md +++ b/public/static/docs/command-reference/add.md @@ -89,10 +89,9 @@ reproducible. ## Options - `-R`, `--recursive` - determines the files to add by searching each target - directory and its subdirectories for data files. For each file found, a new + directory and its subdirectories for data files. If there are no directories + among the `targets`, this option is ignored. For each file found, a new DVC-file is created using the process described in this command's description. - `targets` is expected to contain one or more directories for this option to - have effect. - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an entry is added to `.dvc/state`, while nothing is added to the cache. (The @@ -107,11 +106,11 @@ reproducible. - `-v`, `--verbose` - displays detailed tracing information. -- `-f`, `--file` - specify name of the DVC-file it generates. This option works - only if there is a single target. By default the name of the generated - DVC-file is `.dvc`, where `` is the file name of the given - target. This option allows to set the name and the path of the generated - DVC-file. +- `-f`, `--file` - specify name of the DVC-file it generates. If more than a + single target are provided, this option is ignored. By default, the name of + the generated DVC-file is `.dvc`, where `` is the file name of + the given target. This option allows to set the name and the path of the + generated DVC-file. ## Example: Single file diff --git a/public/static/docs/command-reference/checkout.md b/public/static/docs/command-reference/checkout.md index f2c9286d9c..1b1d02e9cc 100644 --- a/public/static/docs/command-reference/checkout.md +++ b/public/static/docs/command-reference/checkout.md @@ -69,16 +69,15 @@ be pulled from remote storage using `dvc pull`. ## Options -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to update by tracking dependencies to - the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not checkout files referenced in later stages than the - `targets`. - -- `-R`, `--recursive` - `targets` is expected to contain one or more directories - for this option to have effect. Determines the files to checkout by searching - each target directory and its subdirectories for DVC-files to inspect. +- `-d`, `--with-deps` - determines files to update by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not checkout + files referenced in later stages than the `targets`. + +- `-R`, `--recursive` - determines the files to checkout by searching each + target directory and its subdirectories for DVC-files to inspect. If there are + no directories among the `targets`, this option is ignored. - `-f`, `--force` - does not prompt when removing workspace files. Changing the current set of DVC-files with `git checkout` can result in the need for DVC to diff --git a/public/static/docs/command-reference/commit.md b/public/static/docs/command-reference/commit.md index 0f2c0861bb..bb5399cdef 100644 --- a/public/static/docs/command-reference/commit.md +++ b/public/static/docs/command-reference/commit.md @@ -71,15 +71,15 @@ reproducibility in those cases. ## Options -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to commit by tracking dependencies to - the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not commit files referenced in later stages than the `targets`. - -- `-R`, `--recursive` - `targets` is expected to contain one or more directories - for this option to have effect. Determines the files to commit by searching - each target directory and its subdirectories for DVC-files to inspect. +- `-d`, `--with-deps` - determines files to commit by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not commit + files referenced in later stages than the `targets`. + +- `-R`, `--recursive` - determines the files to commit by searching each target + directory and its subdirectories for DVC-files to inspect. If there are no + directories among the `targets`, this option is ignored. - `-f`, `--force` - commit data even if hash values for dependencies or outputs did not change. diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md index 9e189c8d66..97b5f7f46f 100644 --- a/public/static/docs/command-reference/config.md +++ b/public/static/docs/command-reference/config.md @@ -65,11 +65,11 @@ This is the main section with the general config options: - `core.loglevel` - log level that the `dvc` command should use. Possible values are: `info`, `debug`, `warning`, `error`. -- `core.remote` - name of the remote that should be used by default. +- `core.remote` - name of the remote storage that should be used by default. - `core.interactive` - whether to always ask for confirmation before reproducing - each [stage](/doc/command-reference/run) in `dvc repro`. By default this - behavior requires the use of option `-i` in that command. Accepts values + each [stage](/doc/command-reference/run) in `dvc repro`. (Normally, this + behavior requires the use of option `-i` in that command.) Accepts values `true` and `false`. - `core.analytics` - used to turn off @@ -102,8 +102,8 @@ for more details.) This section contains the following options: - `cache.dir` - set/unset cache directory location. A correct value must be either an absolute path or a path **relative to the config file location**. - The default value is `cache` that, resolved relative to the default project - config location, results in `.dvc/cache`. + The default value is `cache`, that resolves to `.dvc/cache` (relative to the + project config file location). > See also helper command `dvc cache dir` to intuitively set this config > option, properly transforming paths relative to the current working @@ -153,10 +153,10 @@ for more details.) This section contains the following options: > set. - `cache.shared` - permissions for newly created or downloaded cache files and - directories. The default permissions are `0o664`(rw-r--r--) for files and - `0o755`(rwxr-xr-x) for directories. The only accepted value right now is - `group`, which makes DVC use `0o664`(rw-rw-r--) for files and - `0o775`(rwxrwxr-x) for directories, which is useful when you are using a a + directories. The default is `0o664`(rw-r--r--) for files and `0o755` + (rwxr-xr-x) for directories. The only accepted value right now is `group`, + which makes DVC use `0o664` (rw-rw-r--) for files and `0o775` (rwxrwxr-x) for + directories, which is useful when you are using a a [shared development server](/doc/use-cases/shared-development-server). - `cache.local` - name of a local remote to use as cache directory. (Refer to @@ -191,15 +191,15 @@ learn more about the state file (database) that is used for optimization. - `state.row_limit` - maximum number of entries in the state database, which affects the physical size of the state file itself, as well as the performance - of certain DVC operations. The bigger the limit, the longer the file hash - history that DVC can keep, in order to avoid sequential hash recalculations. - The default limit is set to 10,000,000 rows. + of certain DVC operations. The default is 10,000,000 rows. The bigger the + limit, the longer the file hash history that DVC can keep, in order to avoid + sequential hash recalculations. - `state.row_cleanup_quota` - percentage of the state database that is going to - be deleted when it hits the `state.row_limit`. When an entry in the database - is used (e.g. during the `dvc status`) dvc updates the timestamp on that entry - so that when it needs to cleanup the database it could sort them by the - timestamp and remove the oldest ones. Default quota is set to 50(percent). + be deleted when it hits the `state.row_limit`. Default quota is set to 50%. + When an entry in the database is used (e.g. during the `dvc status`), DVC + updates the timestamp on that entry. This way, when the database needs a + cleanup, DVC can sort entries chronologically, and remove the oldest ones. ## Example: Set the debug level diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md index 06b613b154..7c4e9de196 100644 --- a/public/static/docs/command-reference/fetch.md +++ b/public/static/docs/command-reference/fetch.md @@ -58,8 +58,9 @@ specified, the set of data files to fetch is determined by analyzing all DVC-files in the current branch, unless `--all-branches` or `--all-tags` is specified. -The default remote is used unless `--remote` is specified. See `dvc remote add` -for more information on how to configure different remote storage providers. +The default remote is used (see `dvc config core.remote`) unless the `--remote` +option is used. See `dvc remote add` for more information on how to configure +different remote storage. `dvc fetch`, `dvc pull`, and `dvc push` are related in that these 3 commands perform data synchronization among local and remote storage. The specific way in @@ -73,25 +74,24 @@ by `dvc fetch` (unless the `-a` or `-T` options are used). - `-r REMOTE`, `--remote REMOTE` - name of the [remote storage](/doc/command-reference/remote) to fetch from (see - `dvc remote list`). If not specified, the default remote is used (see - `dvc config core.remote`). The argument `REMOTE` is a remote name defined - using the `dvc remote` command. + `dvc remote list`). The argument `REMOTE` is a remote name defined using + `dvc remote`. -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to download by tracking dependencies - to the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not fetch files referenced in later stages than the `targets`. +- `-d`, `--with-deps` - determines files to download by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not fetch + files referenced in later stages than the `targets`. - `-R`, `--recursive` - determines the files to fetch by searching each target - directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. + directory and its subdirectories for DVC-files to inspect. If there are no + directories among the `targets`, this option is ignored. - `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle - the downloading of files from the remote. Using more jobs may improve the - total download speed if a combination of small and large files are being - fetched. The default value is `4 * cpu_count()`. For SSH remotes default is - just 4. + the downloading of files from the remote. The default value is + `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs + may improve the total download speed if a combination of small and large files + are being fetched. - `-a`, `--all-branches` - fetch cache for all Git branches instead of just the current workspace. This means DVC may download files needed to reproduce diff --git a/public/static/docs/command-reference/gc.md b/public/static/docs/command-reference/gc.md index 8b0041f57d..b08a44a465 100644 --- a/public/static/docs/command-reference/gc.md +++ b/public/static/docs/command-reference/gc.md @@ -57,8 +57,8 @@ restored using `dvc fetch`, as long as they have previously been uploaded with if `-c` option is specified. - `-j`, `--jobs` - garbage collector parallelism level. The default value is - `4 * cpu_count()`. For SSH remotes default is 4. For now only some phases of - GC are parallel. + `4 * cpu_count()`. For SSH remotes, the default is just `4`. For now only some + phases of GC are parallel. - `-f`, `--force` - force garbage collection. Skip confirmation prompt. diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md index 36ebc1fcba..79c8d7e871 100644 --- a/public/static/docs/command-reference/get.md +++ b/public/static/docs/command-reference/get.md @@ -52,10 +52,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 output will be placed inside of - it. + location to place the downloaded file in (instead of using the current working + directory). If an existing directory is specified, the output will be placed + inside of it. - `--rev` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to @@ -63,8 +62,8 @@ name. default branch) is used by default when this option is not specified. - `--show-url` - instead of downloading the file or directory, just print the - storage location (URL) of the target data. `path` is expected to represent a - cached, DVC-tracked file for this option to have effect. + storage location (URL) of the target data. If `path` is a Git-tracked file, + this option is ignored. - `-h`, `--help` - prints the usage/help message, and exit. @@ -154,7 +153,7 @@ again, like in the previous example. But this time, clone it first to see `dvc get` in action inside a DVC project. ```dvc -$ git clone git@github.com:iterative/example-get-started.git +$ git clone https://github.com/iterative/example-get-started $ cd example-get-started ``` diff --git a/public/static/docs/command-reference/import-url.md b/public/static/docs/command-reference/import-url.md index d497e59282..245928d7b5 100644 --- a/public/static/docs/command-reference/import-url.md +++ b/public/static/docs/command-reference/import-url.md @@ -108,12 +108,9 @@ up to date from the external data source. ## Options -- `-f`, `--file` - specify name of the DVC-file it generates. By default the - DVC-file name generated is `.dvc`, where `` is file name of the - output (`out`). The stage file is placed in the same directory where - `dvc import-url` is run by default, but `-f` can be used to change this - location and file name, by including a path in the provided value (e.g. - `-f stages/stage.dvc`). +- `-f`, `--file` - specify a path and/or file name for the DVC-file created by + this command (e.g. `-f stages/stage.dvc`). This overrides the default file + name: `.dvc`, where `` is the file name of the output (`out`). - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md index b97bf79a57..18ca551639 100644 --- a/public/static/docs/command-reference/import.md +++ b/public/static/docs/command-reference/import.md @@ -69,10 +69,9 @@ data artifact from the source repo. ## Options - `-o`, `--out` - specify a path (directory and/or file name) to the desired - location to place the imported data and import stage (DVC-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 - output will be placed inside of it. + location to place the imported file in (instead of using the current working + directory). If an existing directory is specified, the output will be placed + inside of it. - `--rev` - commit hash, branch or tag name, etc. (any [Git revision](https://git-scm.com/docs/revisions)) of the repository to diff --git a/public/static/docs/command-reference/metrics/diff.md b/public/static/docs/command-reference/metrics/diff.md index 23a2fc3052..0b60a70116 100644 --- a/public/static/docs/command-reference/metrics/diff.md +++ b/public/static/docs/command-reference/metrics/diff.md @@ -35,13 +35,11 @@ They're calculated between two commits (hash, branch, tag, or any ## Options -- `--targets` - specific metric files or directories to calculate metrics - differences for. If omitted (default), this command uses all metric files - found in both Git references. +- `--targets` - limit the comparison to these specific metric files. - `-R`, `--recursive` - determines the metric files to use by searching each - target directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. + target directory and its subdirectories for DVC-files to inspect. If there are + no directories among the `targets`, this option is ignored. - `-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 diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md index 919828c3ac..cf48d0ccc5 100644 --- a/public/static/docs/command-reference/metrics/show.md +++ b/public/static/docs/command-reference/metrics/show.md @@ -89,8 +89,8 @@ compares them with a previous version. `-aT` flag. - `-R`, `--recursive` - determines the metric files to show by searching each - target directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. + target directory and its subdirectories for DVC-files to inspect. If there are + no directories among the `targets`, this option is ignored. - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md index 7449cdf2fa..1702ba6717 100644 --- a/public/static/docs/command-reference/pull.md +++ b/public/static/docs/command-reference/pull.md @@ -59,10 +59,10 @@ reflinks or hardlinks to put it in the workspace without copying. See ## Options -- `-r REMOTE`, `--remote REMOTE` specifies which remote to pull from (see - `dvc remote list`). The value for `REMOTE` is a name defined using - `dvc remote`. If the option is not specified, then the default remote - (configured with the `core.config` config option) is used. +- `-r REMOTE`, `--remote REMOTE` - name of the + [remote storage](/doc/command-reference/remote) to pull from (see + `dvc remote list`). The argument `REMOTE` is a remote name defined using + `dvc remote`. - `-a`, `--all-branches` - determines the files to download by examining DVC-files in all Git branches instead of just those present in the current @@ -73,26 +73,26 @@ reflinks or hardlinks to put it in the workspace without copying. See to save different experiments or project checkpoints. Note that both options can be combined, for example using the `-aT` flag. -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to download by tracking dependencies - to the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not pull files referenced in later stages than the `targets`. +- `-d`, `--with-deps` - determines files to download by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not pull + files referenced in later stages than the `targets`. - `-R`, `--recursive` - determines the files to pull by searching each target - directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. + directory and its subdirectories for DVC-files to inspect. If there are no + directories among the `targets`, this option is ignored. - `-f`, `--force` - does not prompt when removing workspace files, which occurs when these file no longer match the current DVC-file references. This option surfaces behavior from the `dvc fetch` and `dvc checkout` commands because `dvc pull` in effect performs those 2 functions in a single command. -- `-j JOBS`, `--jobs JOBS` - specifies number of jobs to run simultaneously - while downloading files from the remote. The effect is to control the number - of files downloaded simultaneously. Default is `4 * cpu_count()`. For example - with `-j 1` DVC downloads one file at a time, with `-j 2` it downloads two at - a time, and so forth. For SSH remotes default is set to 4. +- `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle + the downloading of files from the remote. The default value is + `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs + may improve the total download speed if a combination of small and large files + are being fetched. - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md index 1c0f6c87eb..d736486ef5 100644 --- a/public/static/docs/command-reference/push.md +++ b/public/static/docs/command-reference/push.md @@ -71,10 +71,10 @@ to push. ## Options -- `-r REMOTE`, `--remote REMOTE` specifies which remote to push from (see - `dvc remote list`). The value for `REMOTE` is a name defined using - `dvc remote`. If the option is not specified, then the default remote - (configured with the `core.config` config option) is used. +- `-r REMOTE`, `--remote REMOTE` - name of the + [remote storage](/doc/command-reference/remote) to push from (see + `dvc remote list`). The argument `REMOTE` is a remote name defined using + `dvc remote`. - `-a`, `--all-branches` - determines the files to upload by examining DVC-files in all Git branches instead of just those present in the current workspace. @@ -84,21 +84,21 @@ to push. to save different experiments or project checkpoints. Note that both options can be combined, for example using the `-aT` flag. -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to upload by tracking dependencies to - the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not push files referenced in later stages than the `targets`. +- `-d`, `--with-deps` - determines files to upload by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not push + files referenced in later stages than the `targets`. - `-R`, `--recursive` - determines the files to push by searching each target - directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. - -- `-j JOBS`, `--jobs JOBS` - specifies number of jobs to run simultaneously - while uploading files to the remote. The effect is to control the number of - files uploaded simultaneously. Default is `4 * cpu_count()`. For example with - `-j 1` DVC uploads one file at a time, with `-j 2` it uploads two at a time, - and so forth. For SSH remotes default is set to 4. + directory and its subdirectories for DVC-files to inspect. If there are no + directories among the `targets`, this option is ignored. + +- `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle + the uploading of files from the remote. The default value is + `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs + may improve the total download speed if a combination of small and large files + are being fetched. - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/remote/add.md b/public/static/docs/command-reference/remote/add.md index cd5dbd93b0..16807cf87e 100644 --- a/public/static/docs/command-reference/remote/add.md +++ b/public/static/docs/command-reference/remote/add.md @@ -70,7 +70,7 @@ Use `dvc config` to unset/change the default remote as so: your config that you don't want to track and share through Git (credentials, private locations, etc). -- `-d`, `-default` - commands that require a remote (such as `dvc pull`, +- `-d`, `--default` - commands that require a remote (such as `dvc pull`, `dvc push`, `dvc fetch`) will be using this remote by default to upload or download data (unless their `-r` option is used). diff --git a/public/static/docs/command-reference/remove.md b/public/static/docs/command-reference/remove.md index ae05f7c2aa..f35498dcba 100644 --- a/public/static/docs/command-reference/remove.md +++ b/public/static/docs/command-reference/remove.md @@ -27,8 +27,8 @@ how it can be used to replace or modify files that are tracked by DVC. ## Options -- `-o`, `--outs` (default) - remove outputs described in the given `targets`, - keep the DVC-files. +- `-o`, `--outs` - remove the outputs described in the given `targets`, keep the + DVC-files themselves. **This is the default behavior.** - `-p`, `--purge` - remove outputs and DVC-files. diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md index 4f26a4dad0..77bf692cfa 100644 --- a/public/static/docs/command-reference/repro.md +++ b/public/static/docs/command-reference/repro.md @@ -85,8 +85,8 @@ and only execute the final stage. ## Options - `-f`, `--force` - reproduce a pipeline, regenerating its results, even if no - changes were found. By default this executes all of its stages but it can be - limited with the `targets` argument and `-s`, `-p`, or `-c` options. + changes were found. This executes all of the stages by default, but it can be + limited with the `targets` argument, or the `-s`, `-p`, `-c` options. - `-s`, `--single-item` - reproduce only a single stage by turning off the recursive search for changed dependencies. Multiple stages are executed @@ -101,8 +101,8 @@ and only execute the final stage. independent unit. - `-R`, `--recursive` - determines the stages to reproduce by searching each - target directory and its subdirectories for DVC-files to inspect. `targets` is - expected to contain one or more directories for this option to have effect. + target directory and its subdirectories for DVC-files to inspect. If there are + no directories among the `targets`, this option is ignored. - `--no-commit` - do not save outputs to cache. (See `dvc run`.) Useful when running different experiments and you don't want to fill up the cache with diff --git a/public/static/docs/command-reference/run.md b/public/static/docs/command-reference/run.md index 2742e25d41..e6542ad3af 100644 --- a/public/static/docs/command-reference/run.md +++ b/public/static/docs/command-reference/run.md @@ -35,16 +35,21 @@ instead of `"` to wrap the `command` if there are environment variables in it, that you want to be evaluated dynamically. E.g. `dvc run -d script.sh './myscript.sh $MYENVVAR'` -Unless the `-f` options is used, by default the DVC-file name generated is -`.dvc`, where `` is file name of the first output (`-o`, `-O`, `-m`, -or `-M` option). If neither `-f`, nor outputs are specified, the stage name -defaults to `Dvcfile`. - Since `dvc run` provides a way to build a dependency graph using dependencies and outputs to connect different stages, it checks the graph's integrity before creating a new stage. For example, for every output there should be only one stage that explicitly specifies it. There should be no cycles, etc. +Unless the `-f` options is used, the stage file (DVC-file) is generated in the +current working directory and named `.dvc`, where `` is file name of +the first output (`-o`, `-O`, `-m`, or `-M` option). If neither `-f` nor outputs +are specified, the file name defaults to `Dvcfile`. + +Note that `dvc run` executes the given `command` in order to check it's validity +and to write the defined outputs, unless an equivalent stage file exists (same +dependencies, outputs, and `command` to execute) that has already been run and +is up to date. + Note that `dvc repro` provides an interface to check state and reproduce this graph (pipeline) later. This concept is similar to the one of the [Make](https://www.gnu.org/software/make/) in software build automation, but DVC @@ -112,12 +117,10 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.) because they are small enough to be tracked by Git directly. See also the difference between `-o` and `-O`. -- `-f`, `--file` - specify stage file name. By default the DVC-file name - generated is `.dvc`, where `` is file name of the first output - (`-o`, `-O`, `-m`, or `-M` option). By default, The stage file is placed in - the same directory where `dvc run` is used, but `-f` can be used to change - this location, by including a path in the provided value (e.g. - `-f stages/stage.dvc`). +- `-f`, `--file` - specify a path and/or file name for the stage file generated + by this command (e.g. `-f stages/stage.dvc`). This overrides the default file + name: `.dvc`, where `` is the file name of the first output or + metric. - `-c`, `--cwd` (_deprecated_) - Use `-f` and `-w` to change the name and location (working directory) of a stage file. @@ -141,18 +144,14 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.) determined by the logic described in the `-f` option) without asking for confirmation. -- `--ignore-build-cache` - has an effect if an equivalent stage file exists - (same dependencies, outputs, and `command` to execute), that has been already - executed, and is up to date. In this case, `dvc run` won't normally execute - the `command` again. The exception is when the existing stage is considered - always changed (see `--always-changed` option). This option gives a way to - forcefully execute the `command` anyway. Useful if the command's code is +- `--ignore-build-cache` - forcefully execute the `command` again, even if an + equivalent stage file exists. Useful if the command's code is non-deterministic (meaning it produces different outputs from the same list of inputs). - `--remove-outs` (_deprecated_) - remove stage outputs before executing the `command`. If `--no-exec` specified outputs are removed anyway. See - `dvc remove` as well for more details. This is the default behavior. + `dvc remove` as well for more details. **This is the default behavior.** - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an entry is added to `.dvc/state`, while nothing is added to the cache. @@ -164,8 +163,8 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.) `dvc status` will report it as `always changed` and `dvc repro` will always execute it. - > Note that a DVC-file without dependencies is considered always changed, so - > this option has no effect in that case. + > Note that DVC-files without dependencies are automatically considered + > "always changed", so this option has no effect in those cases. - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/status.md b/public/static/docs/command-reference/status.md index 6d16483660..d7634b1250 100644 --- a/public/static/docs/command-reference/status.md +++ b/public/static/docs/command-reference/status.md @@ -96,17 +96,16 @@ workspace) is different from remote storage. Bringing the two into sync requires ## Options -- `-d`, `--with-deps` - one or more `targets` should be specified for this - option to have effect. Determines files to check by tracking dependencies to - the target DVC-files (stages). By traversing all stage dependencies, DVC - searches backward from the target stages in the corresponding pipelines. This - means DVC will not show changes occurring in later stages than the `targets`. - Applies whether or not `--cloud` is specified. +- `-d`, `--with-deps` - determines files to check by tracking dependencies to + the target DVC-files (stages). If no `targets` are provided, this option is + ignored. By traversing all stage dependencies, DVC searches backward from the + target stages in the corresponding pipelines. This means DVC will not show + changes occurring in later stages than the `targets`. Applies whether or not + `--cloud` is specified. - `-c`, `--cloud` - enables comparison against a remote. (See `dvc remote`.). If - no `--remote` option has been given, DVC will compare against the default - remote (specified in the `core.remote` config option). Otherwise the - comparison will be against the remote specified in the `--remote` option. + no `--remote` option is provided, DVC will compare against the default remote + (specified in the `core.remote` config option). - `-r REMOTE`, `--remote REMOTE` - specifies which remote storage (see `dvc remote list`) to compare against. The argument, `REMOTE`, is a remote