From 16e50a4a77b03c97037100e1d4e2f59f38f266f9 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Tue, 10 Mar 2020 12:52:09 -0600 Subject: [PATCH 1/4] term: flag -> option as much as possible --- public/static/docs/changelog/0.35.md | 9 +++++---- public/static/docs/command-reference/add.md | 2 +- public/static/docs/command-reference/cache/dir.md | 2 +- public/static/docs/command-reference/diff.md | 6 +++--- public/static/docs/command-reference/fetch.md | 2 +- public/static/docs/command-reference/pull.md | 12 ++++++------ public/static/docs/command-reference/push.md | 4 ++-- .../static/docs/command-reference/remote/modify.md | 10 +++++----- public/static/docs/command-reference/repro.md | 2 +- public/static/docs/tutorials/pipelines.md | 4 ++-- public/static/docs/user-guide/analytics.md | 6 +++--- 11 files changed, 30 insertions(+), 29 deletions(-) diff --git a/public/static/docs/changelog/0.35.md b/public/static/docs/changelog/0.35.md index d91118078f..f4efc2260f 100644 --- a/public/static/docs/changelog/0.35.md +++ b/public/static/docs/changelog/0.35.md @@ -39,10 +39,11 @@ improvements) we have done in the last few months: 1 file not changed, 0 files modified, 1 file added, 0 files deleted, size was increased by 15.3 MB ``` -- We've introduced the DVC commit command and `dvc run/repro/add --no-commit` - flag to give a way to **avoid uncontrolled cache growth** and as a way to save - some runs of `dvc repro`. In the future we plan to have “do-not-cache-my-data” - as a default mode for `dvc run`, `dvc add` and `dvc repro`. +- We've introduced the `dvc commit` command and `dvc run/repro/add --no-commit` + option to give a way to **avoid uncontrolled cache growth** and as a way to + save some runs of `dvc repro`. In the future we plan to have + “do-not-cache-my-data”as a default mode for `dvc run`, `dvc add` and + `dvc repro`. - **SSH remotes (data storage) support** - config options to set port, key files, timeouts, password, etc + improved stability and Windows support! diff --git a/public/static/docs/command-reference/add.md b/public/static/docs/command-reference/add.md index b7a68fb348..c0209e6572 100644 --- a/public/static/docs/command-reference/add.md +++ b/public/static/docs/command-reference/add.md @@ -69,7 +69,7 @@ to work with directory hierarchies with `dvc add`: 1. With `dvc add --recursive`, the hierarchy is traversed and every file is added individually as described above. This means every file has its own DVC-file, and a corresponding cached file is created (unless the - `--no-commit` flag is used). + `--no-commit` option is used). 2. When not using `--recursive` a DVC-file is created for the top of the directory (with default name `dirname.dvc`). Every file in the hierarchy is added to the cache (unless the `--no-commit` option is used), but DVC does diff --git a/public/static/docs/command-reference/cache/dir.md b/public/static/docs/command-reference/cache/dir.md index fa02b112d5..3a118f30a1 100644 --- a/public/static/docs/command-reference/cache/dir.md +++ b/public/static/docs/command-reference/cache/dir.md @@ -38,7 +38,7 @@ for the config file. private locations, etc). - `-u`, `--unset` - remove the `cache.dir` config option from the config file. - Don't provide a `value` when using this flag. + Don't provide a `value` argument when employing this flag. - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/diff.md b/public/static/docs/command-reference/diff.md index 17b62299f6..d064751442 100644 --- a/public/static/docs/command-reference/diff.md +++ b/public/static/docs/command-reference/diff.md @@ -79,9 +79,9 @@ Preparing to download data from 'https://remote.dvc.org/get-started' ... ``` -The `-T` flag passed to `dvc fetch` makes sure we have all the data files -related to all existing tags in the repo. You may see the available tags of our -example repo [here](https://github.com/iterative/example-get-started/tags). +With the `-T` option, `dvc fetch` makes sure that we have all the data files +related to all existing Git tags in the repo. You may see the available tags of +our example repo [here](https://github.com/iterative/example-get-started/tags). diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md index 7c4e9de196..43de2aab6c 100644 --- a/public/static/docs/command-reference/fetch.md +++ b/public/static/docs/command-reference/fetch.md @@ -246,7 +246,7 @@ $ dvc status -c One could do a simple `dvc fetch` to get all the data, but what if you only want to retrieve the data up to our third stage, `train.dvc`? We can use the -`--with-deps` (or `-d`) flag: +`--with-deps` (or `-d`) option: ```dvc $ dvc fetch --with-deps train.dvc diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md index 1702ba6717..16fe689831 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 missing files and directories from +[remote storage](/doc/command-reference/remote) to the cache, based +on the [DVC-files](/doc/user-guide/dvc-file-format) in the +workspace. And link the downloaded files into the workspace. ## Synopsis @@ -137,8 +137,8 @@ default remote. The only files considered in this case are what is listed in the ## Example: With dependencies -Demonstrating the `--with-deps` flag requires a larger example. First, assume a -[pipeline](/doc/command-reference/pipeline) has been setup with these +Demonstrating the `--with-deps` option requires a larger example. First, assume +a [pipeline](/doc/command-reference/pipeline) has been setup with these [stages](/doc/command-reference/run): ```dvc diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md index d736486ef5..ecde92bdde 100644 --- a/public/static/docs/command-reference/push.md +++ b/public/static/docs/command-reference/push.md @@ -137,8 +137,8 @@ $ dvc push data.zip.dvc ## Example: With dependencies -Demonstrating the `--with-deps` flag requires a larger example. First, assume a -[pipeline](/doc/command-reference/pipeline) has been setup with these +Demonstrating the `--with-deps` option requires a larger example. First, assume +a [pipeline](/doc/command-reference/pipeline) has been setup with these [stages](/doc/command-reference/run): ```dvc diff --git a/public/static/docs/command-reference/remote/modify.md b/public/static/docs/command-reference/remote/modify.md index f87e65c858..df289e5a57 100644 --- a/public/static/docs/command-reference/remote/modify.md +++ b/public/static/docs/command-reference/remote/modify.md @@ -26,9 +26,9 @@ positional arguments: ## Description -Remote `name` and `option` name are required. Option names are remote type -specific. See `dvc remote add` and -[Available settings](#available-settings-per-storage-type) section below for a +Remote `name` and `option` name are required. Option names are specific to the +remote type. See `dvc remote add` and the +[available settings](#available-settings-per-storage-type) section below for a list of remote storage types. This command modifies a `remote` section in the project's @@ -37,8 +37,8 @@ manual editing could be used to change the configuration. ## Options -- `-u`, `--unset` - delete configuration value for given `option`. Don't provide - a `value` when using this flag. +- `-u`, `--unset` - delete configuration value for the given `option`. Don't + provide a `value` when employing this flag. - `--global` - save remote configuration to the global config (e.g. `~/.config/dvc/config`) instead of `.dvc/config`. diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md index 77bf692cfa..3bbe198173 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. + irregardless of this option. - `-v`, `--verbose` - displays detailed tracing information. diff --git a/public/static/docs/tutorials/pipelines.md b/public/static/docs/tutorials/pipelines.md index c54d6e34ef..bdd6cf2b1b 100644 --- a/public/static/docs/tutorials/pipelines.md +++ b/public/static/docs/tutorials/pipelines.md @@ -375,8 +375,8 @@ master: > Since the dataset for this example is extremely simplified to make it faster > to run this pipeline, the exact metric numbers may vary. -The `-a` flag in the command above tells `dvc metrics show` to show the value -for all Git branches. +The `-a` option above tells `dvc metrics show` to show the metrics value for all +Git branches. Feel free to commit the remaining changes with Git. diff --git a/public/static/docs/user-guide/analytics.md b/public/static/docs/user-guide/analytics.md index 7315559cea..cdbb3778d3 100644 --- a/public/static/docs/user-guide/analytics.md +++ b/public/static/docs/user-guide/analytics.md @@ -57,6 +57,6 @@ However, if you want to opt out of DVC's analytics, you can disable it via $ dvc config core.analytics false ``` -This will disable it for the project. Alternatively, you can -specify `--global` or `--system` flags to disable it for an active user or for -everyone in the system. +This will disable it for the project. Alternatively, you can use +the `--global` or `--system` options of `dvc config` to disable analytics for +the active user or for everyone in the system, respectively. From 5c4a19fa781ccc8c894db8789c547281ea41bd31 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Mar 2020 14:36:25 -0600 Subject: [PATCH 2/4] term: review usage of "option" up til status cmd ref --- public/static/docs/changelog/0.18.md | 2 +- public/static/docs/changelog/0.35.md | 17 ++++++----- .../static/docs/command-reference/commit.md | 13 ++++---- .../static/docs/command-reference/config.md | 30 +++++++++---------- public/static/docs/command-reference/gc.md | 4 +-- .../static/docs/command-reference/get-url.md | 7 +++-- public/static/docs/command-reference/init.md | 12 ++++---- .../docs/command-reference/metrics/add.md | 2 +- .../docs/command-reference/metrics/index.md | 12 ++++---- public/static/docs/command-reference/pull.md | 6 ++-- public/static/docs/command-reference/push.md | 14 ++++----- public/static/docs/command-reference/run.md | 18 +++++------ .../static/docs/command-reference/status.md | 12 ++++---- 13 files changed, 76 insertions(+), 73 deletions(-) diff --git a/public/static/docs/changelog/0.18.md b/public/static/docs/changelog/0.18.md index 92021df8a4..27890748e4 100644 --- a/public/static/docs/changelog/0.18.md +++ b/public/static/docs/changelog/0.18.md @@ -32,7 +32,7 @@ really excited to share the progress with you: computation): ![](/static/img/0.18-progress.gif) - Pipeline visualization via command line. Just run `dvc pipeline show` with - `ascii` option and a target: ![](/static/img/0.18-pipeline.gif) + option `--ascii` and a target: ![](/static/img/0.18-pipeline.gif) - Many hidden gems: `dvc repro` dry and interactive modes, improved overall commands verbosity and revised commands help. diff --git a/public/static/docs/changelog/0.35.md b/public/static/docs/changelog/0.35.md index f4efc2260f..774fd547d6 100644 --- a/public/static/docs/changelog/0.35.md +++ b/public/static/docs/changelog/0.35.md @@ -8,9 +8,10 @@ Now, let's **highlight the changes** (not including bug fixes, and minor improvements) we have done in the last few months: - 🏷 We received a lot of feedback that using Git branches is not always an - optimal way to manage experiments. We have added an option to **support Git - tags** (Git commits are coming). The new option `-T` or `--all-tags` is - supported by all DVC commands that support`-a` or `--all-branches`. + optimal way to manage experiments. We have added an option to **use all Git + tags** (Git commits are coming), `-T` or `--all-tags`, which is supported by + all DVC commands that also have `-a` or `--all-branches` (use all Git + branches). - 📖 The [Get Started](/doc/get-started/agenda) section has been simplified (e.g. to use tags instead of branches) and extended. We have also prepared a @@ -39,11 +40,11 @@ improvements) we have done in the last few months: 1 file not changed, 0 files modified, 1 file added, 0 files deleted, size was increased by 15.3 MB ``` -- We've introduced the `dvc commit` command and `dvc run/repro/add --no-commit` - option to give a way to **avoid uncontrolled cache growth** and as a way to - save some runs of `dvc repro`. In the future we plan to have - “do-not-cache-my-data”as a default mode for `dvc run`, `dvc add` and - `dvc repro`. +- We've introduced the `dvc commit` command and the + `dvc run/repro/add --no-commit` option to give a way to **avoid uncontrolled + cache growth** and as a way to save some runs of `dvc repro`. In the future we + plan to have“do-not-cache-my-data”as a default mode for `dvc run`, `dvc add` + and `dvc repro`. - **SSH remotes (data storage) support** - config options to set port, key files, timeouts, password, etc + improved stability and Windows support! diff --git a/public/static/docs/command-reference/commit.md b/public/static/docs/command-reference/commit.md index 4ab9eeb2d4..4ba72d7d71 100644 --- a/public/static/docs/command-reference/commit.md +++ b/public/static/docs/command-reference/commit.md @@ -131,7 +131,7 @@ $ dvc pull --all-branches --all-tags ## Example: Rapid iterations Sometimes we want to iterate through multiple changes to configuration, code, or -data, trying multiple options to improve the output of a stage. To avoid filling +data, trying different ways to improve the output of a stage. To avoid filling the cache with undesired intermediate results, we can run a single stage with `dvc run --no-commit`, or reproduce an entire pipeline using `dvc repro --no-commit`. This prevents data from being pushed to cache. When @@ -140,17 +140,18 @@ files in the cache. In the `featurize.dvc` stage, `src/featurize.py` is executed. A useful change to make is adjusting a parameter to `CountVectorizer` in that script. Namely, -adjusting the `max_features` option in this line changes the resulting model: +adjusting the `max_features` value in the line below changes the resulting +model: ```python bag_of_words = CountVectorizer(stop_words='english', max_features=6000, ngram_range=(1, 2)) ``` -This option not only changes the trained model, it also introduces a change that -would cause the `featurize.dvc`, `train.dvc` and `evaluate.dvc` stages to -execute if we ran `dvc repro`. But if we want to try several values for this -option and save only the best result to the cache, we can execute as so: +This edit introduces a change that would cause the `featurize.dvc`, `train.dvc` +and `evaluate.dvc` stages to execute if we ran `dvc repro`. But if we want to +try several values for `max_features` and save only the best result to the +cache, we can run it like this: ```dvc $ dvc repro --no-commit evaluate.dvc diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md index 27b3284a61..f440ddab9c 100644 --- a/public/static/docs/command-reference/config.md +++ b/public/static/docs/command-reference/config.md @@ -23,15 +23,15 @@ This command reads and updates the DVC configuration files. By default (if none of `--local`, `--global`, or `--system` is provided) a project's config (`.dvc/config`) file is read or modified. This file is by default meant to be tracked by Git and should not contain sensitive and/or user-specific information -(passwords, SSH keys, etc). Use `--local`, `--global`, or `--system` options -instead to override project's settings, for sensitive, or user-specific -settings. +(passwords, SSH keys, etc). Use `--local`, `--global`, or `--system` command +options (flags) instead to override project's settings, for sensitive, or +user-specific settings. -If the config option `value` is not provided and `--unset` option is not used, -this command returns the current value of the config option, if found in the -corresponding config file. +If the config option `value` is not provided and the `--unset` command option is +not used, this command returns the current value of the config option, if found +in the corresponding config file. -## Options +## Command options (flags) - `-u`, `--unset` - remove a specified config option from a config file. @@ -69,7 +69,7 @@ This is the main section with the general config options: - `core.interactive` - whether to always ask for confirmation before reproducing each [stage](/doc/command-reference/run) in `dvc repro`. (Normally, this - behavior requires the use of option `-i` in that command.) Accepts values: + behavior requires using the `-i` option of that command.) Accepts values: `true` and `false`. - `core.analytics` - used to turn off @@ -124,7 +124,7 @@ for more details.) This section contains the following options: option on forces you to run `dvc unprotect` before updating a file, providing an additional layer of security to your data. - We highly recommend enabling this option when `cache.type` is set to + We highly recommend enabling `cache.protected` when `cache.type` is set to `hardlink` or `symlink`. - `cache.type` - link type that DVC should use to link data files from cache to @@ -137,16 +137,16 @@ for more details.) This section contains the following options: ⚠️ If you manually set `cache.type` to `hardlink` or `symlink`, **you will corrupt the cache** if you modify tracked data files in the workspace. See the - `cache.protected` config option above and corresponding `dvc unprotect` - command to modify files safely. + `cache.protected` option above, and corresponding `dvc unprotect` command to + modify files safely. There are pros and cons to different link types. Refer to [File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache) for a full explanation of each one. - To apply changes to this option in the workspace, by restoring all file - links/copies from cache, please use `dvc checkout --relink`. See - [checkout options](/doc/command-reference/checkout#options) for more details. + To apply changes to this config option in the workspace, by restoring all file + links/copies from cache, please use `dvc checkout --relink`. See that + command's [options](/doc/command-reference/checkout#options) for more details. - `cache.slow_link_warning` - used to turn off the warnings about having a slow cache link type. These warnings are thrown by `dvc pull` and `dvc checkout` @@ -223,7 +223,7 @@ $ dvc config core.remote myremote ``` > Note that this is equivalent to using `dvc remote add` with the -> `-d`/`--default` option. +> `-d`/`--default` flag. ## Example: Default remotes diff --git a/public/static/docs/command-reference/gc.md b/public/static/docs/command-reference/gc.md index b08a44a465..2f765bb0aa 100644 --- a/public/static/docs/command-reference/gc.md +++ b/public/static/docs/command-reference/gc.md @@ -53,8 +53,8 @@ restored using `dvc fetch`, as long as they have previously been uploaded with the current commit (unless `-a` or `-T` are also used). The default remote is used unless a specific one is given with `-r`. -- `-r`, `--remote` - name of the remote storage to collect unused objects from - if `-c` option is specified. +- `-r`, `--remote` - name of the remote storage to collect unused objects from, + if the `-c` option is used. - `-j`, `--jobs` - garbage collector parallelism level. The default value is `4 * cpu_count()`. For SSH remotes, the default is just `4`. For now only some diff --git a/public/static/docs/command-reference/get-url.md b/public/static/docs/command-reference/get-url.md index 4d7fccf6a6..551e924c9f 100644 --- a/public/static/docs/command-reference/get-url.md +++ b/public/static/docs/command-reference/get-url.md @@ -96,10 +96,11 @@ same file name: $ dvc get-url s3://bucket/path ``` -By default DVC expects your AWS CLI is already +By default, DVC expects that AWS CLI is already [configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). -DVC will be using default AWS credentials file to access S3. To override some of -these settings, you could the options described in `dvc remote modify`. + +DVC will use the AWS credentials file to access S3. To override the +configuration, you can the parameters described in `dvc remote modify`. > We use the `boto3` library to and communicate with AWS. The following API > methods may be performed: diff --git a/public/static/docs/command-reference/init.md b/public/static/docs/command-reference/init.md index 903f2efdfe..9693e73fab 100644 --- a/public/static/docs/command-reference/init.md +++ b/public/static/docs/command-reference/init.md @@ -14,8 +14,8 @@ DVC works on top of a Git repository by default. This enables all features, providing the most value. It means that `dvc init` (without flags) expects to run in a Git repository root (a `.git/` directory should be present). -The command options can be used to start an alternative workflow for advanced -scenarios like monorepos, automation, etc: +The command [options](#options) can be used to start an alternative workflow for +advanced scenarios: - [Initializing DVC in subdirectories](#initializing-dvc-in-subdirectories) - support for monorepos, nested DVC projects, etc. @@ -38,7 +38,7 @@ single Git repository providing isolation and granular project management. #### When is this useful? -This option is mostly used in the scenario of a +`--subdir` is mostly used in the scenario of a [monorepo](https://en.wikipedia.org/wiki/Monorepo), but also can be used in other workflows when such isolation and/or advanced granularity is needed. @@ -118,8 +118,8 @@ won't download or checkout data for the `data-B.dvc` file. ### Initializing DVC without Git -In rare cases, `--no-scm` option might be used to initialize DVC in a directory -that is not part of a Git repository, or to make DVC ignore Git. Examples +In rare cases, the `--no-scm` option might be desirable: to initialize DVC in a +directory that is not part of a Git repo, or to make DVC ignore Git. Examples include: - SCM other than Git is being used. Even though there are DVC features that @@ -137,7 +137,7 @@ e.g. managing `.gitignore` files on `dvc add` or `dvc run` to avoid committing DVC-tracked files into Git, or `dvc diff` and `dvc metrics diff` that accept Git-revisions to compare, etc. -DVC sets the `core.no_scm` option value to `true` in the DVC +DVC sets the `core.no_scm` config option value to `true` in the DVC [config](/doc/command-reference/config) when it is initialized this way. It means that even if the project was Git-tracked already or Git is initialized in it later, DVC keeps operating in the detached from Git mode. diff --git a/public/static/docs/command-reference/metrics/add.md b/public/static/docs/command-reference/metrics/add.md index 8b571b5a3e..da00da97cd 100644 --- a/public/static/docs/command-reference/metrics/add.md +++ b/public/static/docs/command-reference/metrics/add.md @@ -18,7 +18,7 @@ defines the given `path` as an output, marking `path` as a [project metric](/doc/command-reference/metrics) to track. Note that outputs can also be marked as metrics via the `-m` or `-M` options of -the `dvc run` command. +`dvc run`. 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 diff --git a/public/static/docs/command-reference/metrics/index.md b/public/static/docs/command-reference/metrics/index.md index 4abc570c91..cf2eae60e5 100644 --- a/public/static/docs/command-reference/metrics/index.md +++ b/public/static/docs/command-reference/metrics/index.md @@ -23,8 +23,8 @@ positional arguments: ## Description DVC has the ability to mark a certain stage outputs as files -containing metrics to track. (See `--metrics` option of `dvc run`.) Metrics are -project-specific numeric values e.g. `AUC`, `ROC`, etc. DVC itself does not +containing metrics to track. (See the `--metrics` option of `dvc run`.) Metrics +are project-specific numeric values e.g. `AUC`, `ROC`, etc. DVC itself does not ascribe any specific meaning for these numbers. Usually these numbers are produced by the model evaluation script and serve as a way to compare and pick the best performing experiment. @@ -54,10 +54,10 @@ $ dvc run -d code/evaluate.py -M data/eval.json \ python code/evaluate.py ``` -> `-M|--metrics-no-cache` is telling DVC to mark `data/eval.json` as a metric -> file. Using this option is equivalent to using `-O|--outs-no-cache` and then -> running `dvc metrics add data/eval.json` to explicitly mark `data/eval.json` -> as a metric file. +> `-M` (`--metrics-no-cache`) is telling DVC to mark `data/eval.json` as a +> metric file. Using this option is equivalent to using `-O` (`--outs-no-cache`) +> and then running `dvc metrics add data/eval.json` to explicitly mark +> `data/eval.json` as a metric file. Now let's print metric values that we are tracking in this project: diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md index 16fe689831..d392a1853c 100644 --- a/public/static/docs/command-reference/pull.md +++ b/public/static/docs/command-reference/pull.md @@ -31,8 +31,8 @@ The `dvc pull` command allows one to retrieve data from remote storage. `dvc pull` has the same effect as running `dvc fetch` and `dvc checkout` immediately after that. -If the `--remote REMOTE` option is not specified, then the default remote, -configured with the `core.config` config option, is used. See `dvc remote`, +If the `--remote` option is not used, then the default remote is used +(configured with the `core.config` config option). See `dvc remote`, `dvc config` and this [example](/doc/get-started/configure) for more information on how to configure a remote. @@ -187,5 +187,5 @@ and searched backwards through the pipeline for data files to download. Because the `model.p.dvc` stage occurs later, its data was not pulled. Then we ran `dvc pull` specifying the last stage, `model.p.dvc`, and its data -was downloaded. Finally, we ran `dvc pull` with no options to make sure that all +was downloaded. Finally, we ran `dvc pull` with no flags to make sure that all data was already pulled with the previous commands. diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md index ecde92bdde..8da075a847 100644 --- a/public/static/docs/command-reference/push.md +++ b/public/static/docs/command-reference/push.md @@ -36,7 +36,7 @@ Under the hood a few actions are taken: - The push command by default uses all [DVC-files](/doc/user-guide/dvc-file-format) in the workspace. - The command line options listed below will either limit or expand the set of + The command options listed below will either limit or expand the set of DVC-files to consult. - For each output referenced from each selected DVC-file, DVC finds @@ -47,11 +47,11 @@ Under the hood a few actions are taken: - Upload the cache files missing from remote storage, if any, to the remote. The DVC `push` command always works with a remote storage, and it is an error if -none are specified on the command line nor in the configuration. If a -`--remote REMOTE` option is not specified, then the default remote, configured -with the `core.config` config option, is used. See `dvc remote`, `dvc config` -and this [example](/doc/get-started/configure) for more information on how to -configure a remote. +none are specified on the command line nor in the configuration. If the +`--remote` option is not used, then the default remote, configured with the +`core.config` config option, is used. See `dvc remote`, `dvc config` and this +[example](/doc/get-started/configure) for more information on how to configure a +remote. With no arguments, just `dvc push` or `dvc push --remote REMOTE`, it uploads only the files (or directories) that are new in the local repository to remote @@ -191,7 +191,7 @@ and searched backwards through the pipeline for data files to upload. Because the `model.p.dvc` stage occurs later, its data was not pushed. Then we ran `dvc push` specifying the last stage, `model.p.dvc`, and its data -was uploaded. Finally, we ran `dvc push` and `dvc status` with no options to +was uploaded. Finally, we ran `dvc push` and `dvc status` with no flags to double check that all data had been uploaded. ## Example: What happens in the cache diff --git a/public/static/docs/command-reference/run.md b/public/static/docs/command-reference/run.md index e6542ad3af..d3ba9ceb6b 100644 --- a/public/static/docs/command-reference/run.md +++ b/public/static/docs/command-reference/run.md @@ -26,8 +26,8 @@ options) DVC can later connect each stage by building a dependency graph ([DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph)). This graph is used by DVC to restore a full data [pipeline](/doc/command-reference/pipeline). -The remaining terminal input provided to `dvc run` after the options (`-`/`--` -arguments) will become the required `command` argument. Please wrap the +The remaining terminal input provided to `dvc run` after the command options +(`-`/`--` flags) will become the required `command` argument. Please wrap the `command` with `"` quotes if there are special characters in it like `|` (pipe) or `<`, `>` (redirection) that would otherwise apply to `dvc run` itself e.g. `dvc run -d script.sh "./script.sh > /dev/null 2>&1"`. Use single quotes `'` @@ -175,8 +175,9 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.) ## Examples -A trivial example to play with, try different set of options to see how they -work. You don't need any actual data or scripts to play with this example: +A first example to play with is to try the different command options, to see +what they do. No pre-existing data or source code is needed, as we can use +placeholders and in-line commands directly in `dvc run`: ```dvc $ mkdir example && cd example @@ -184,14 +185,13 @@ $ git init $ dvc init $ mkdir data $ dvc run -d data -o metric -f metric.dvc "echo '1' >> metric" - Running command: - echo '1' >> metric -Saving information to 'metric.dvc'. + echo '1' >> metric +WARNING: 'data' is empty. -To track the changes with git run: +To track the changes with git, run: - git add .gitignore metric.dvc + git add .gitignore metric.dvc ``` > See [DVC-File Format](/doc/user-guide/dvc-file-format) for more details on the diff --git a/public/static/docs/command-reference/status.md b/public/static/docs/command-reference/status.md index a44960df56..6ca0821e7c 100644 --- a/public/static/docs/command-reference/status.md +++ b/public/static/docs/command-reference/status.md @@ -26,11 +26,11 @@ yet tracked by DVC) and must be added again (with `dvc add`) or reproduced (with modes, _local_ and _cloud_ are triggered by using the `--cloud` or `--remote` options: -| Mode | CLI Option | Description | -| ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| local | _none_ | Comparisons are made between data files in the workspace and corresponding files in the cache directory (e.g. `.dvc/cache`) | -| remote | `--remote` | Comparisons are made between the cache, and the given remote. Remote storage is defined using the `dvc remote` command. | -| remote | `--cloud` | Comparisons are made between the cache, and the default remote, typically defined with `dvc remote --default`. | +| Mode | Command option | Description | +| ------ | -------------- | --------------------------------------------------------------------------------------------------------------------------- | +| local | _none_ | Comparisons are made between data files in the workspace and corresponding files in the cache directory (e.g. `.dvc/cache`) | +| remote | `--remote` | Comparisons are made between the cache, and the given remote. Remote storage is defined using the `dvc remote` command. | +| remote | `--cloud` | Comparisons are made between the cache, and the default remote, typically defined with `dvc remote --default`. | DVC determines which data and code files to compare by analyzing all [DVC-files](/doc/user-guide/dvc-file-format) in the workspace (the @@ -105,7 +105,7 @@ workspace) is different from remote storage. Bringing the two into sync requires `--cloud` is specified. - `-c`, `--cloud` - enables comparison against a remote. (See `dvc remote`.). If - no `--remote` option is provided, DVC will compare against the default remote + the `--remote` option is not used, DVC will compare against the default remote (specified in the `core.remote` config option). - `-r REMOTE`, `--remote REMOTE` - specifies which remote storage (see From 29b0dfcbd91e2c598ee18f8d1000f740ddfad808 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Mar 2020 01:04:45 -0600 Subject: [PATCH 3/4] api ref: more reviews for term "option" --- public/static/docs/command-reference/fetch.md | 2 +- .../docs/command-reference/metrics/add.md | 32 ++++++++-------- .../docs/command-reference/metrics/diff.md | 24 ++++++------ .../docs/command-reference/metrics/modify.md | 32 ++++++++-------- .../docs/command-reference/metrics/show.md | 37 +++++++++---------- .../docs/command-reference/pipeline/show.md | 8 ++-- public/static/docs/command-reference/pull.md | 2 +- public/static/docs/command-reference/push.md | 4 +- .../docs/command-reference/remote/add.md | 14 +++---- .../docs/command-reference/remote/default.md | 6 +-- .../docs/command-reference/remote/modify.md | 21 ++++++----- public/static/docs/command-reference/run.md | 14 +++---- .../docs/get-started/connect-code-and-data.md | 8 ++-- public/static/docs/get-started/index.md | 2 +- public/static/docs/get-started/initialize.md | 2 +- public/static/docs/get-started/metrics.md | 3 +- public/static/docs/get-started/visualize.md | 6 +-- public/static/docs/install/completion.md | 8 ++-- public/static/docs/tutorials/pipelines.md | 6 +-- .../understanding-dvc/related-technologies.md | 8 ++-- .../use-cases/sharing-data-and-model-files.md | 3 +- .../docs/user-guide/external-dependencies.md | 2 +- .../user-guide/large-dataset-optimization.md | 10 ++--- 23 files changed, 126 insertions(+), 128 deletions(-) diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md index d11c0e4bf1..4e34086792 100644 --- a/public/static/docs/command-reference/fetch.md +++ b/public/static/docs/command-reference/fetch.md @@ -6,7 +6,7 @@ Get tracked files or directories from ## Synopsis ```usage -usage: dvc fetch [-h] [-q | -v] [-j JOBS] +usage: dvc fetch [-h] [-q | -v] [-j ] [-r ] [-a] [-T] [-d] [-R] [targets [targets ...]] diff --git a/public/static/docs/command-reference/metrics/add.md b/public/static/docs/command-reference/metrics/add.md index 7cecdee788..1d746bbd86 100644 --- a/public/static/docs/command-reference/metrics/add.md +++ b/public/static/docs/command-reference/metrics/add.md @@ -6,7 +6,7 @@ Mark output file as a ## Synopsis ```usage -usage: dvc metrics add [-h] [-q | -v] [-t TYPE] [-x XPATH] path +usage: dvc metrics add [-h] [-q | -v] [-t ] [-x ] path positional arguments: path Path to a metric file. @@ -31,27 +31,27 @@ specific value, if the file contains multiple metrics. See the ## Options -- `-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. +- `-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. `htsv`/`hcsv` are the same as `tsv`/`csv`, but the values in the first row of the file will be used as the field names and should be used to address columns in the `--xpath` option. -- `-x`, `--xpath` - specify a path within a metric file to get a specific metric - value. Should be used if the metric file contains multiple numbers and you - want to use only one of them. Only a single path is allowed. It will be saved - into the corresponding DVC-file, and used by `dvc metrics show` to determine - how to display metrics. The accepted value depends on the metric file type - (`--type` option): - - - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or - [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options. - For example, `"AUC"` extracts the value from the following JSON-formatted - metric file: `{"AUC": "0.624652"}`. +- `-x `, `--xpath ` - specify a path within a metric file to get a + specific metric value. Should be used if the metric file contains multiple + numbers and you want to use only one of them. Only a single path is allowed. + It will be saved into the corresponding DVC-file, and used by + `dvc metrics show` to determine how to display metrics. The accepted value + depends on the metric file type (`--type` option): + + - For `json` - see [JSONPath](https://goessner.net/articles/JsonPath/) or + [jsonpath-ng](https://github.com/h2non/jsonpath-ng) to know the syntax. For + example, `"AUC"` extracts the value from the following JSON-formatted metric + file: `{"AUC": "0.624652"}`. - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based. - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. First row is used to specify column names and is not included into index. diff --git a/public/static/docs/command-reference/metrics/diff.md b/public/static/docs/command-reference/metrics/diff.md index 0096c5c6e9..f1495d06d2 100644 --- a/public/static/docs/command-reference/metrics/diff.md +++ b/public/static/docs/command-reference/metrics/diff.md @@ -8,8 +8,8 @@ commits in the DVC repository, or between a commit and the ```usage usage: dvc metrics diff [-h] [-q | -v] - [--targets [TARGETS [TARGETS ...]]] - [-t TYPE] [-x XPATH] [-R] [--show-json] + [--targets [ [ ...]]] + [-t ] [-x ] [-R] [--show-json] [a_ref] [b_ref] positional arguments: @@ -35,26 +35,26 @@ They're calculated between two commits (hash, branch, tag, or any ## Options -- `--targets` - limit the comparison to these specific metric files. +- `--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. 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 - how to parse and format metics for display. See `dvc metrics show` for more - details. +- `-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. See + `dvc metrics show` for more details. This option will override `type` and `xpath` defined in the corresponding DVC-file. If no `type` is provided or found in the DVC-file, DVC will try to detect it based on file extension. -- `-x`, `--xpath` - specify a path within a metric file to show changes for a - specific metric value only. Should be used if the metric file contains - multiple numbers and you want to use only one of them. Only a single path is - allowed. It will override `xpath` defined in the corresponding DVC-file. See - `dvc metrics show` for more details. +- `-x `, `--xpath ` - specify a path within a metric file to show + changes for a specific metric value only. Should be used if the metric file + contains multiple numbers and you want to use only one of them. Only a single + path is allowed. It will override `xpath` defined in the corresponding + DVC-file. See `dvc metrics show` for more details. - `--show-json` - prints the command's output in easily parsable JSON format, instead of a human-readable table. diff --git a/public/static/docs/command-reference/metrics/modify.md b/public/static/docs/command-reference/metrics/modify.md index 26792056df..257afcaacd 100644 --- a/public/static/docs/command-reference/metrics/modify.md +++ b/public/static/docs/command-reference/metrics/modify.md @@ -6,7 +6,7 @@ options such as `type` or `xpath`. See full [options](#options) info below. ## Synopsis ```usage -usage: dvc metrics modify [-h] [-q | -v] [-t TYPE] [-x XPATH] path +usage: dvc metrics modify [-h] [-q | -v] [-t ] [-x ] path positional arguments: path Path to a metric file. @@ -32,27 +32,27 @@ ERROR: failed to modify metric file settings - ## Options -- `-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. +- `-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. `htsv`/`hcsv` are the same as `tsv`/`csv`, but the values in the first row of the file will be used as the field names and should be used to address columns in the `--xpath` option. -- `-x`, `--xpath` - specify a path within a metric file to get a specific metric - value. Should be used if the metric file contains multiple numbers and you - want to use only one of them. Only a single path is allowed. It will be saved - into the corresponding DVC-file, and used by `dvc metrics show` to determine - how to display metrics. The accepted value depends on the metric file type - (`--type` option): - - - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or - [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options. - For example, `"AUC"` extracts the value from the following JSON-formatted - metric file: `{"AUC": "0.624652"}`. +- `-x `, `--xpath ` - specify a path within a metric file to get a + specific metric value. Should be used if the metric file contains multiple + numbers and you want to use only one of them. Only a single path is allowed. + It will be saved into the corresponding DVC-file, and used by + `dvc metrics show` to determine how to display metrics. The accepted value + depends on the metric file type (`--type` option): + + - For `json` - see [JSONPath](https://goessner.net/articles/JsonPath/) or + [jsonpath-ng](https://github.com/h2non/jsonpath-ng) to know the syntax. For + example, `"AUC"` extracts the value from the following JSON-formatted metric + file: `{"AUC": "0.624652"}`. - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based. - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. First row is used to specify column names and is not included into index. diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md index f4f67fe79e..210df40304 100644 --- a/public/static/docs/command-reference/metrics/show.md +++ b/public/static/docs/command-reference/metrics/show.md @@ -6,9 +6,8 @@ formatting. ## Synopsis ```usage -usage: dvc metrics show [-h] [-q | -v] - [-t TYPE] [-x XPATH] [-a] [-T] [-R] - [targets [targets ...]] +usage: dvc metrics show [-h] [-q | -v] [-t ] [-x ] + [-a] [-T] [-R] [targets [targets ...]] positional arguments: targets Metric files or directories (see -R) to show @@ -43,9 +42,9 @@ compares them with a previous version. ## Options -- `-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. +- `-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 @@ -56,19 +55,19 @@ compares them with a previous version. DVC-file. If no `type` is provided or found in the DVC-file, DVC will try to detect it based on file extension. -- `-x`, `--xpath` - specify a path within a metric file to get a specific metric - value. Should be used if the metric file contains multiple numbers and you - want to use only one of them. Only a single path is allowed. It will override - `xpath` defined in the corresponding DVC-file. The accepted value depends on - the metric file type (`--type` option): - - - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or - [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options. - For example, `"AUC"` extracts the value from the following JSON-formatted - metric file: `{"AUC": "0.624652"}`. You can also filter on certain values, - for example `"$.metrics[?(@.deviation_mse<0.30) & (@.value_mse>0.4)]"` - extracts only the values for model versions if they meet the given - conditions from the metric file: +- `-x `, `--xpath ` - specify a path within a metric file to get a + specific metric value. Should be used if the metric file contains multiple + numbers and you want to use only one of them. Only a single path is allowed. + It will override `xpath` defined in the corresponding DVC-file. The accepted + value depends on the metric file type (`--type` option): + + - For `json` - see [JSONPath](https://goessner.net/articles/JsonPath/) or + [jsonpath-ng](https://github.com/h2non/jsonpath-ng) to know the syntax. For + example, `"AUC"` extracts the value from the following JSON-formatted metric + file: `{"AUC": "0.624652"}`. You can also filter on certain values, for + example `"$.metrics[?(@.deviation_mse<0.30) & (@.value_mse>0.4)]"` extracts + only the values for model versions if they meet the given conditions from + the metric file: `{"metrics": [{"dataset": "train", "deviation_mse": 0.173461, "value_mse": 0.421601}]}` - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based. - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. diff --git a/public/static/docs/command-reference/pipeline/show.md b/public/static/docs/command-reference/pipeline/show.md index c6afb09ce1..8fa9e70fd1 100644 --- a/public/static/docs/command-reference/pipeline/show.md +++ b/public/static/docs/command-reference/pipeline/show.md @@ -28,11 +28,11 @@ instead of stages. ## Options -- `-c`, `--commands` - show pipeline as a list (graph, if `--ascii` or `--dot` - option is specified) of commands instead of paths to DVC-files. +- `-c`, `--commands` - show pipeline as a list (diagram if `--ascii` or `--dot` + is used) of commands instead of paths to DVC-files. -- `-o`, `--outs` - show pipeline as a list (graph, if `--ascii` or `--dot` - option is specified) of stage outputs instead of paths to DVC-files. +- `-o`, `--outs` - show pipeline as a list (diagram if `--ascii` or `--dot` is + used) of stage outputs instead of paths to DVC-files. - `--ascii` - visualize pipeline. It will print a graph (ASCII) instead of a list of path to DVC-files. (`less` pager may be used, see diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md index 413b6cac1f..b55eba9bf5 100644 --- a/public/static/docs/command-reference/pull.md +++ b/public/static/docs/command-reference/pull.md @@ -35,7 +35,7 @@ The default remote is used (see `dvc config core.remote`) unless the `--remote` option is used. See `dvc remote` for more information on how to configure a remote. -With no arguments, just `dvc pull` or `dvc pull --remote REMOTE`, it downloads +With no arguments, just `dvc pull` or `dvc pull --remote `, it downloads only the files (or directories) missing from the workspace by searching all [DVC-files](/doc/user-guide/dvc-file-format) currently in the project. It will not download files associated with earlier commits diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md index f220402b68..e746b91d44 100644 --- a/public/static/docs/command-reference/push.md +++ b/public/static/docs/command-reference/push.md @@ -6,8 +6,8 @@ Upload tracked files or directories to ## Synopsis ```usage -usage: dvc push [-h] [-q | -v] [-j JOBS] - [-r REMOTE] [-a] [-T] [-d] [-R] +usage: dvc push [-h] [-q | -v] [-j ] + [-r ] [-a] [-T] [-d] [-R] [targets [targets ...]] positional arguments: diff --git a/public/static/docs/command-reference/remote/add.md b/public/static/docs/command-reference/remote/add.md index 09cafb59c9..d90839ef36 100644 --- a/public/static/docs/command-reference/remote/add.md +++ b/public/static/docs/command-reference/remote/add.md @@ -187,8 +187,7 @@ $ dvc remote add myremote "azure://" 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 to prevent shell from misprocessing the - > command. + > 💡 Make sure the value is quoted so its processed correctly by the console. - `container name` - this is the top-level container in your Azure Storage Account under which all the files for this remote will be uploaded. If the @@ -213,8 +212,9 @@ $ dvc remote modify myremote gdrive_client_secret Note that GDrive remotes are not "trusted" by default. This means that the [`verify`](/doc/command-reference/remote/modify#available-settings-for-all-remotes) -option is enabled on this type of storage, so DVC recalculates the file hashes -upon download (e.g. `dvc pull`), to make sure that these haven't been modified. +parameter is enabled on this type of storage, so DVC recalculates the file +hashes upon download (e.g. `dvc pull`), to make sure that these haven't been +modified. > Please note our [Privacy Policy (Google APIs)](/doc/user-guide/privacy). @@ -298,8 +298,8 @@ check that you are able to connect both ways to the remote location, with tools like `ssh` and `sftp` (GNU/Linux). > Note that your server's SFTP root might differ from its physical root (`/`). -> (On Linux, see the `ChrootDirectory` config option in `/etc/ssh/sshd_config`.) -> In these cases, the path component in the SSH URL (e.g. `/path/to/dir` above) +> (On Linux, see the `ChrootDirectory` setting in `/etc/ssh/sshd_config`.) In +> these cases, the path component in the SSH URL (e.g. `/path/to/dir` above) > should be specified relative to the SFTP root instead. For example, on some > Sinology NAS drives, the SFTP root might be in directory `/volume1`, in which > case you should use path `/path/to/dir` instead of `/volume1/path/to/dir`. @@ -372,7 +372,7 @@ $ cat .dvc/config ## Example: Customize an S3 remote -Add an Amazon S3 remote as the _default_ (via `-d` option), and modify its +Add an Amazon S3 remote as the _default_ (via the `-d` option), and modify its region. > 💡 Before adding an S3 remote, be sure to diff --git a/public/static/docs/command-reference/remote/default.md b/public/static/docs/command-reference/remote/default.md index 41a9cb8b4e..d8ced38453 100644 --- a/public/static/docs/command-reference/remote/default.md +++ b/public/static/docs/command-reference/remote/default.md @@ -22,9 +22,9 @@ positional arguments: ## Description -You can query/set/replace/unset default remote using options of this command. If -the `name` of the remote is not provided and `--unset` is not specified, this -command returns the name of the default remote. +You can query/set/replace/unset default remote using the options of this +command. If the `name` of the remote is not provided and `--unset` is not +specified, this command returns the name of the default remote. ```dvc $ dvc remote default myremote diff --git a/public/static/docs/command-reference/remote/modify.md b/public/static/docs/command-reference/remote/modify.md index 2f5b7035b2..91ae1feff3 100644 --- a/public/static/docs/command-reference/remote/modify.md +++ b/public/static/docs/command-reference/remote/modify.md @@ -26,8 +26,8 @@ positional arguments: ## Description -Remote `name` and `option` name are required. Option names are specific to the -remote type. See `dvc remote add` and the +Remote `name` and `option` name are required. Config option names are specific +to the remote type. See `dvc remote add` and the [available settings](#available-settings-per-storage-type) section below for a list of remote storage types. @@ -35,10 +35,10 @@ This command modifies a `remote` section in the project's [config file](/doc/command-reference/config). Alternatively, `dvc config` or manual editing could be used to change the configuration. -## Options +## Command options (flags) -- `-u`, `--unset` - delete configuration value for the given `option`. Don't - provide a `value` when employing this flag. +- `-u`, `--unset` - delete configuration value for the given config `option`. + Don't provide a `value` when employing this flag. - `--global` - save remote configuration to the global config (e.g. `~/.config/dvc/config`) instead of `.dvc/config`. @@ -61,7 +61,7 @@ manual editing could be used to change the configuration. ## Available parameters for all remotes -The following options are available for all remote types: +The following config options are available for all remote types: - `verify` - upon downloading cache files (`dvc pull`, `dvc fetch`) DVC will recalculate the file hashes upon download (e.g. `dvc pull`) to make @@ -175,7 +175,7 @@ these settings, you could use the following options: ``` > \* - `grant_read`, `grant_read_acp`, `grant_write_acp` and - > `grant_full_control` options are mutually exclusive with `acl` option. + > `grant_full_control` params are mutually exclusive with `acl`. > > \*\* - default ACL grantees are overwritten. Grantees are AWS accounts > identifiable by `id` (AWS Canonical User ID), `emailAddress` or `uri` @@ -239,7 +239,8 @@ For more information on configuring Azure Storage connection strings, visit > The connection string contains access to data and is inserted into the > `.dvc/config file.` Therefore, it is safer to add the connection string with -> the `--local` option, enforcing it to be written to a Git-ignored config file. +> the `--local` command option, enforcing it to be written to a Git-ignored +> config file. @@ -407,7 +408,7 @@ remote `url` (and data under it) you set up above. - `gss_auth` - use Generic Security Services authentication if available on host (for example, [with kerberos](https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface#Relationship_to_Kerberos)). - Using this option requires `paramiko[gssapi]`, which is currently only + Using this param requires `paramiko[gssapi]`, which is currently only supported by our pip package, and could be installed with `pip install 'dvc[ssh_gssapi]'`. Other packages (Conda, Windows, and MacOS PKG) do not support it. @@ -478,7 +479,7 @@ remote `url` (and data under it) you set up above. > Note that the specified password will be inserted into the `.dvc/config` > file. Therefore, it's recommended to configure it using the `--local` - > option, which writes it to a Git-ignored config file. (Or use the + > command option, which writes it to a Git-ignored config file. (Or use the > `ask_password` parameter instead.) - `ask_password` - ask each time for the password to use for any `auth` method. diff --git a/public/static/docs/command-reference/run.md b/public/static/docs/command-reference/run.md index a75455ed26..c97553f36f 100644 --- a/public/static/docs/command-reference/run.md +++ b/public/static/docs/command-reference/run.md @@ -8,7 +8,7 @@ command and execute the command. ```usage usage: dvc run [-h] [-q | -v] [-d ] [-o ] [-O ] [-m ] [-M ] [-f ] [-c ] - [-w WDIR] [--no-exec] [-y] [--overwrite-dvcfile] + [-w ] [--no-exec] [-y] [--overwrite-dvcfile] [--ignore-build-cache] [--remove-outs] [--no-commit] [--always-changed] command @@ -128,12 +128,12 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.) - `-c `, `--cwd ` (_deprecated_) - Use `-f` and `-w` to change the name and location (working directory) of a stage file. -- `-w`, `--wdir` - specifies a working directory for the `command` to run in. - `dvc run` expects that dependencies, outputs, metric files are specified - relative to this directory. This value is saved in the `wdir` field of the - stage file generated (as a relative path to the location of the DVC-file) and - is used by `dvc repro` to change the working directory before executing the - `command`. +- `-w `, `--wdir ` - specifies a working directory for the `command` + to run in. `dvc run` expects that dependencies, outputs, metric files are + specified relative to this directory. This value is saved in the `wdir` field + of the stage file generated (as a relative path to the location of the + DVC-file) and is used by `dvc repro` to change the working directory before + executing the `command`. - `--no-exec` - create a stage file, but do not execute the `command` defined in it, nor track dependencies or outputs with DVC. In the DVC-file contents, the diff --git a/public/static/docs/get-started/connect-code-and-data.md b/public/static/docs/get-started/connect-code-and-data.md index 65d4aabcb8..0cece0c266 100644 --- a/public/static/docs/get-started/connect-code-and-data.md +++ b/public/static/docs/get-started/connect-code-and-data.md @@ -124,8 +124,8 @@ wdir: . > [pipeline](/doc/get-started/pipeline), or in other words, instructions on how > to build a ML model (data file) from previous data files (or directories). -Let's briefly mention what the options used above mean for this particular -example: +Let's briefly mention what the command options used above mean for this +particular example: `-f prepare.dvc` specifies a name for the DVC-file (pipeline stage). It's optional but we recommend using it to make your project structure more readable. @@ -145,8 +145,8 @@ to run. This command is saved to the generated DVC-file, and used later by `dvc repro`. Hopefully, `dvc run` (and `dvc repro`) will become intuitive after a few more -Get Started chapters. You can always refer to the their command references to -learn the specific details about how they behave, and all of their options. +Get Started chapters. You can always refer to the the command references for +more details on their behavior and options. diff --git a/public/static/docs/get-started/index.md b/public/static/docs/get-started/index.md index 6c032f690d..55f2a7898e 100644 --- a/public/static/docs/get-started/index.md +++ b/public/static/docs/get-started/index.md @@ -9,7 +9,7 @@ so. Before you start ... -✅ Please, join our [community](/chat) or see these [support](/support) options +✅ Please, join our [community](/chat) or see these [support](/support) channels if you have any questions or need any help. We are very responsive ⚡. ✅ Check out our [GitHub repository](https://github.com/iterative/dvc) and give diff --git a/public/static/docs/get-started/initialize.md b/public/static/docs/get-started/initialize.md index 23a8335ae1..1e227d96c9 100644 --- a/public/static/docs/get-started/initialize.md +++ b/public/static/docs/get-started/initialize.md @@ -2,7 +2,7 @@ There are a few recommended ways to install DVC: OS-specific package/installer, `pip`, `conda`, and Homebrew. See [Installation](/doc/install) for all the -options and details. +alternatives and details. Let's start by creating a workspace we can version with Git. Then run `dvc init` inside to create the DVC project: diff --git a/public/static/docs/get-started/metrics.md b/public/static/docs/get-started/metrics.md index 77dd846643..e91ba6371f 100644 --- a/public/static/docs/get-started/metrics.md +++ b/public/static/docs/get-started/metrics.md @@ -22,8 +22,7 @@ from the `features/test.pkl` file and produces a numeric value) can be marked as a metric, for example by using the `-M` option of `dvc run`. -> Please, refer to the `dvc metrics` command documentation to see more available -> options and details. +> Please, refer to the `dvc metrics` command documentation to see more details. Let's save the updated results: diff --git a/public/static/docs/get-started/visualize.md b/public/static/docs/get-started/visualize.md index 73648ed981..5b7e5c293f 100644 --- a/public/static/docs/get-started/visualize.md +++ b/public/static/docs/get-started/visualize.md @@ -4,9 +4,9 @@ Now that we have built our pipeline, we need a good way to visualize it to be able to wrap our heads around it. Luckily, DVC allows us to do that without leaving the terminal, making the experience distraction-less. -We are using `--ascii` option below to better illustrate this pipeline. Please, -refer to the `dvc pipeline show` documentation to explore other options this -command supports (e.g. `.dot` files that can be used then in other tools). +We are using the `--ascii` option below to better illustrate this pipeline. +Please, refer to `dvc pipeline show` to explore other options this command +supports (e.g. `.dot` files that can be used then in other tools). ## Stages diff --git a/public/static/docs/install/completion.md b/public/static/docs/install/completion.md index 32a0b8d30a..4c139e3330 100644 --- a/public/static/docs/install/completion.md +++ b/public/static/docs/install/completion.md @@ -11,7 +11,7 @@ instructions below for other DVC installation methods. ## How it works Command completion is usually requested by pressing the `tab` key on your shell, -it will then present the possible options that could follow that command call. +it will then present the possible arguments that can follow that command name. For example: ```dvc @@ -27,11 +27,11 @@ run -- Generate a stage file from a command and execute the command. Depending on what you typed on the command line so far, it completes: - Available DVC commands. -- Options that are available for a particular command. +- Options (flags) that are available for a particular command. - File names that make sense in a given context, such as using them as a target for some commands. -- Arguments for selected options. For example, `dvc repro` completes with stage - files to reproduce. +- Values for certain command arguments. For example, `dvc repro` completes with + stage files to reproduce. ## What shell do you have? diff --git a/public/static/docs/tutorials/pipelines.md b/public/static/docs/tutorials/pipelines.md index 868f410108..d6808bb074 100644 --- a/public/static/docs/tutorials/pipelines.md +++ b/public/static/docs/tutorials/pipelines.md @@ -201,7 +201,7 @@ but made specifically to handle large data files. > Note that for performance with large datasets, DVC can use file links from the > cache to the workspace. This avoids copying actual file contents. Refer to > [File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache) -> to learn which options exist and how to enable them. +> to learn which alternatives exist and how to enable them. @@ -267,8 +267,8 @@ By analyzing dependencies and outputs in DVC-files, we can generate a dependency graph: a series of commands DVC needs to execute. `dvc repro` does this in order to restore a pipeline and reproduce its intermediate or final results. -`dvc pipeline show` helps to visualize pipelines (run it with `-c` option to see -actual commands instead of DVC-files): +`dvc pipeline show` helps to visualize pipelines (run it with the `-c` option to +see actual commands instead of DVC-files): ```dvc $ dvc pipeline show --ascii evaluate.dvc diff --git a/public/static/docs/understanding-dvc/related-technologies.md b/public/static/docs/understanding-dvc/related-technologies.md index 54bff6d1c2..5aef0d1912 100644 --- a/public/static/docs/understanding-dvc/related-technologies.md +++ b/public/static/docs/understanding-dvc/related-technologies.md @@ -103,8 +103,8 @@ Luigi, etc. workflow, are always included in the Git repository. Hence, they can be executed locally with minimal effort. -- DVC is not fundamentally bound to Git, and users have the option of changing - the repository format. +- DVC is not fundamentally bound to Git, and users have the option of using DVC + without SCM. ### Git-LFS (Large File Storage) @@ -113,8 +113,8 @@ Luigi, etc. for datasets and models. No additional databases, servers, or infrastructure are required. -- DVC is not fundamentally bound to Git, and users have the option of changing - the repository format. +- DVC is not fundamentally bound to Git, and users have the option of using DVC + without SCM. - DVC does not add any hooks to the Git repo by default. To checkout data files, the `dvc checkout` command has to be run after each `git checkout` and diff --git a/public/static/docs/use-cases/sharing-data-and-model-files.md b/public/static/docs/use-cases/sharing-data-and-model-files.md index 2e64db59b5..a354c9988e 100644 --- a/public/static/docs/use-cases/sharing-data-and-model-files.md +++ b/public/static/docs/use-cases/sharing-data-and-model-files.md @@ -48,8 +48,7 @@ url = s3://mybucket/myproject remote = myremote ``` -`dvc remote` provides a wide variety of options to configure S3 bucket. For more -information see `dvc remote modify`. +`dvc remote modify` provides a wide variety of options to configure S3 buckets. Let's commit your changes and push your code: diff --git a/public/static/docs/user-guide/external-dependencies.md b/public/static/docs/user-guide/external-dependencies.md index cecbc21f84..c43594fe24 100644 --- a/public/static/docs/user-guide/external-dependencies.md +++ b/public/static/docs/user-guide/external-dependencies.md @@ -27,7 +27,7 @@ supported: > Note that these are a subset of the remote storage types supported by > `dvc remote`. -In order to specify an external dependency for your stage, use the usual '-d' +In order to specify an external dependency for your stage, use the usual `-d` option in `dvc run` with the external path or URL to your desired file or directory. diff --git a/public/static/docs/user-guide/large-dataset-optimization.md b/public/static/docs/user-guide/large-dataset-optimization.md index 2763edb61e..144ffd3aaf 100644 --- a/public/static/docs/user-guide/large-dataset-optimization.md +++ b/public/static/docs/user-guide/large-dataset-optimization.md @@ -41,7 +41,7 @@ system, but may break your workflow since updating hard/sym-linked files tracked by DVC in the workspace causes cache corruption. These 2 link types thus require using cache **protected mode** (see the `cache.protected` config option in `dvc config cache`). Finally, a 4th "linking" -option is to actually copy files from/to the cache, which is safe but +alternative is to actually copy files from/to the cache, which is safe but inefficient – especially for large files (several GBs or more). > Some versions of Windows (e.g. Windows Server 2012+ and Windows 10 Enterprise) @@ -60,7 +60,7 @@ File link type benefits summary: | `symlink` | x | x | | | `copy` | | | x | -Each file linking option is further detailed below, in function of their +Each file linking method is further detailed below, in function of their efficiency: 1. **`reflink`**: Copy-on-write\* links or "reflinks" are the best possible link @@ -113,7 +113,7 @@ $ dvc config cache.type hardlink,symlink $ dvc config cache.protected true ``` -> Refer to `dvc config cache` for more options. +> Refer to `dvc config cache` for more details. Setting `cache.protected` is important with `hardlink` and/or `symlink` cache file link types. Please refer to the @@ -121,8 +121,8 @@ file link types. Please refer to the tracked files under these cache configurations. To make sure that the data files in the workspace are consistent with the -project's `cache.type` option, you may use `dvc checkout --relink`. -See `dvc checkout` for more information. +project's `cache.type` config value, you may use +`dvc checkout --relink`. See `dvc checkout` for more information. --- From 9c3fc81c6e29716c9c37097a459d558869fc93b3 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Mar 2020 02:10:22 -0600 Subject: [PATCH 4/4] list: polish its cmd ref and mention in data registry use case, links --- public/static/docs/command-reference/list.md | 33 +++++++------------ .../docs/command-reference/pipeline/list.md | 5 ++- .../static/docs/use-cases/data-registries.md | 17 ++++++---- 3 files changed, 24 insertions(+), 31 deletions(-) diff --git a/public/static/docs/command-reference/list.md b/public/static/docs/command-reference/list.md index cf61559f00..ee22a40aef 100644 --- a/public/static/docs/command-reference/list.md +++ b/public/static/docs/command-reference/list.md @@ -88,35 +88,26 @@ train.dvc ``` If you open the -[example-get-started project's page](https://github.com/iterative/example-get-started) -you will see something like: +[example-get-started project's page](https://github.com/iterative/example-get-started), +you will see a similar list, except that `model.pkl` will be missing. That's +because its tracked by DVC and not visible to Git. You can find it specified as +an output if you open +[`train.dvc`](https://github.com/iterative/example-get-started/blob/master/train.dvc). -```dvc -.gitignore -README.md -auc.metric -data -evaluate.dvc -featurize.dvc -prepare.dvc -src -train.dvc -``` - -The difference is the `model.pkl` binary file that is DVC-tracked and is not -visible in second listing (which is actually controlled by the `train.dvc`). - -We can now, for example, run: +We can now, for example, run ```dvc $ dvc get https://github.com/iterative/example-get-started model.pkl ``` -to download the model file. +to download the model file (see `dvc get`). ## Example: List all files and directories in a data registry -We can do this recursively, using `-R` option: +Let's imagine a DVC repo used as a +[data registry](/doc/use-cases/data-registries#using-registries), structured +with different datasets in separate directories. We can do this recursively, +using `-R` option: ```dvc $ dvc list -R https://github.com/iterative/dataset-registry @@ -129,7 +120,5 @@ images/.gitignore images/dvc-logo-outlines.png images/dvc-logo-outlines.png.dvc images/owl_sticker.png -images/owl_sticker.png.dvc -images/owl_sticker.svg ... ``` diff --git a/public/static/docs/command-reference/pipeline/list.md b/public/static/docs/command-reference/pipeline/list.md index 8772437424..3ee8cfdb2b 100644 --- a/public/static/docs/command-reference/pipeline/list.md +++ b/public/static/docs/command-reference/pipeline/list.md @@ -10,9 +10,8 @@ usage: dvc pipeline list [-h] [-q | -v] ## Description -`dvc list` displays a list of all existing stages in the project, -grouped in their corresponding [pipeline](/doc/command-reference/pipeline), when -connected. +Displays a list of all existing stages in the project, grouped in +their corresponding [pipeline](/doc/command-reference/pipeline), when connected. > Note that the stages in these lists are in ascending order, that is, from last > to first. diff --git a/public/static/docs/use-cases/data-registries.md b/public/static/docs/use-cases/data-registries.md index 49440fb612..357598427c 100644 --- a/public/static/docs/use-cases/data-registries.md +++ b/public/static/docs/use-cases/data-registries.md @@ -97,19 +97,24 @@ files and directories. ### Listing data (list) -`dvc list` is analogous to using `aws s3 ls` or `ls`: +You may want to explore the contents of a data DVC repo before trying to reuse +its artifacts. The `dvc list` command is analogous to `ls`, or 3rd party tools +like `aws s3 ls`: ```dvc $ dvc list -R https://github.com/iterative/dataset-registry -... +.gitignore README.md -train.dvc -model.pkl -images/faces/ -images/songs/ +get-started/.gitignore +get-started/data.xml +get-started/data.xml.dvc +images/.gitignore +images/dvc-logo-outlines.png ... ``` +> Note that both Git-tracked files and DVC-tracked data/models are listed. + ### Simple download (get) This is analogous to using direct download tools like