Regular updates & plots 1.0 update

content/docs/command-reference/add.md

@@ -24,15 +24,22 @@ into <abbr>data artifacts</abbr> of the <abbr>project</abbr>. By default, these
 are committed to the <abbr>cache</abbr> (use the `--no-commit` option to avoid
 this, and `dvc commit` to finish the process when needed).
 
-Note that [external data](/doc/user-guide/managing-external-data) (targets
+`dvc add` is typically used to version control raw data or initial datasets from
+which data processing [pipelines](/doc/command-reference/pipeline) are built,
+but it can be used to track any large file or directory. We recommend using
+`dvc run` to version control intermediate and final results (like ML models).
+This way you bring data provenance and make your project
+[reproducible](/doc/command-reference/repro).
+
+💡 Note that [external data](/doc/user-guide/managing-external-data) (targets
 outside the <abbr>workspace</abbr>) is supported.
 
 Under the hood, a few actions are taken for each file (or directory) in
 `targets`:
 
 1. Calculate the file hash.
-2. Move the file contents to the cache directory (by default in `.dvc/cache`),
-   using the file hash to form the cached file names. (See
+2. Move the file contents to the cache (by default in `.dvc/cache`), using the
+   file hash to form the cached file names. (See
    [Structure of cache directory](/doc/user-guide/dvc-files-and-directories#structure-of-cache-directory)
    for more details.)
 3. Attempt to replace the file with a link to the cached data (more details
@@ -56,13 +63,15 @@ more details.
 > treated as _changed_ by `dvc repro`, which always executes them. See `dvc run`
 > to learn more about stage files.
 
-By default DVC tries to use reflinks (see
+By default, DVC tries to use reflinks (see
 [File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
 to avoid copying any file contents and to optimize DVC-file operations for large
 files. DVC also supports other link types for use on file systems without
 `reflink` support, but they have to be specified manually. Refer to the
 `cache.type` config option in `dvc config cache` for more information.
 
+### Tracking directories
+
 A `dvc add` target can be an individual file or a directory. There are two ways
 to work with directory hierarchies with `dvc add`:
 
@@ -78,13 +87,6 @@ to work with directory hierarchies with `dvc add`:
    (with `.dir` extension), that in turn points to the files added from the
    hierarchy.
 
-`dvc add` is typically used to version control raw data or initial datasets from
-which data processing [pipelines](/doc/command-reference/pipeline) are built,
-but it can be used to track any large file or directory. We recommend using
-`dvc run` to version control intermediate and final results (like ML models).
-This way you bring data provenance and make your project
-[reproducible](/doc/command-reference/repro).
-
 ## Options
 
 - `-R`, `--recursive` - determines the files to add by searching each target

content/docs/command-reference/metrics/index.md

@@ -71,22 +71,15 @@ to compare and pick the best performing experiment.
 
 ### Default metric files
 
-`dvc metrics` subcommands use all metric files that are specified in `dvc.yaml`
-by default. There's no need to specify metric file names to see these metrics.
-Metric files can be added to `dvc.yaml` with the `--metrics` (`-m`) or
-`--metrics-no-cache` (`-M`) options of `dvc run`, or manually to the `metrics`
-section of a stage in `dvc.yaml`:
+`dvc metrics` subcommands by default use the metric files specified in
+`dvc.yaml` (if any), for example `summary.json` below:
 
 ```yaml
 stages:
   train:
     cmd: python train.py
     deps:
       - users.csv
-    params:
-      - epochs
-      - dropout
-      - lr
     outs:
       - model.pkl
     metrics:

content/docs/command-reference/move.md

@@ -20,16 +20,17 @@ positional arguments:
 `dvc move` is useful when a `src` file or directory has previously been added to
 the <abbr>project</abbr> with `dvc add`, creating a
 [DVC-file](/doc/user-guide/dvc-file-format) (with `src` as a dependency).
-`dvc move` behaves like `mv src dst`, moving `src` to the given `dst` path, but
-it also renames and updates the corresponding DVC-file appropriately.
+`dvc move` behaves similar to `mv src dst`, moving `src` to the given `dst`
+path, but it also renames and updates the corresponding DVC-file appropriately.
 
 > Note that `src` may be a copy or a
 > [link](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
 > to a file in cache. The cached file is not changed by this command.
 
 If the destination path (`dst`) already exists and is a directory, the source
 code file or directory (`src`) is moved unchanged into this folder along with
-the corresponding DVC-file.
+the corresponding DVC-file. Otherwise, any directories in `dst` are created,
+similar to `mkdir -P`.
 
 Let's imagine the following scenario:
 

content/docs/command-reference/plots/diff.md

@@ -6,13 +6,14 @@ plotting them in a single image.
 ## Synopsis
 
 ```usage
-usage: dvc plots diff [-h] [-q | -v] [-t [TEMPLATE]] [-d [DATAFILE]] [-f FILE]
-                     [-s SELECT] [-x X] [-y Y] [--stdout] [--no-csv-header]
-                     [--no-html] [--title TITLE] [--xlab XLAB] [--ylab YLAB]
-                     [revisions [revisions ...]]
+usage: dvc plots diff [-h] [-q | -v] [-t <path>]
+                      [--targets [<path> [<path> ...]]] [-o <path>]
+                      [-x <field>] [-y <field>] [--no-csv-header]
+                      [--show-json] [--title <text>] [--xlab <text>]
+                      [--ylab <text>] [revisions [revisions ...]]
 
 positional arguments:
-  revisions             Git commits to plot from
+  revisions             Git commits to plot from/to
 ```
 
 ## Description
@@ -21,8 +22,8 @@ This command visualize difference between metrics among experiments in the
 repository history. Requires that Git is being used to version the metrics
 files.
 
-The metrics file needs to be specified through `-d`/`--datafile` option. Also, a
-plot can be customized with
+The metrics file needs to be specified through `--targets` option. Also, a plot
+can be customized with
 [plot templates](/doc/command-reference/plots#plot-templates) using the
 `--template` option. To learn more about the file formats and templates please
 see `dvc plots`.
@@ -39,43 +40,38 @@ resulting plot shows all of them in a single output.
 
 This command can work with metric files that are committed to a repository
 history, data files controlled by DVC, or any other file in the workspace. In
-the case of DVC-tracked `datafile`, the `revisions` are used to find the
+the case of DVC-tracked `targets`, the `revisions` are used to find the
 corresponding [DVC-files](/doc/user-guide/dvc-file-format).
 
 ## Options
 
-- `-d [DATAFILE], --datafile [DATAFILE]` - metrics file to visualize.
+- `--targets [TARGETS]` (**required**) - metrics file to visualize.
 
-- `-t [TEMPLATE], --template [TEMPLATE]` -
+- `-t <path>, --template <path>` -
   [plot template](/doc/command-reference/plots#plot-templates) to be injected
   with data. The default template is `.dvc/plots/default.json`. See more details
   in `dvc plots`.
 
-- `-f FILE, --file FILE` - name of the generated file. By default, the output
+- `-o <path>, --out <path>` - name of the generated file. By default, the output
   file name is equal to the input filename with additional `.html` suffix or
-  `.json` suffix for `--no-html` mode.
+  `.json` suffix for `--show-json` mode.
 
-- `--no-html` - do not wrap output Vega specification (JSON) with HTML.
+- `-x <field>` - field name for X axis. An auto-generated `index` field is used
+  by default.
 
-- `-x X` - field name for X axis. An auto-generated `index` field is used by
-  default.
+- `-y <field>` - field name for Y axis. The last column or field found in the
+  `targets` is used by default.
 
-- `-y Y` - field name for Y axis. The last column or field found in the
-  `datafile` is used by default.
+- `--xlab <text>` - X axis title. The X field name is the default title.
 
-- `-s SELECT, --select SELECT` - select which fields or JSONPath to store in the
-  metrics file [metadata](https://vega.github.io/vega/docs/data/). The
-  auto-generated, zero-based `index` column is always included.
+- `--ylab <text>` - Y axis title. The Y field name is the default title.
 
-- `--xlab XLAB` - X axis title. The X field name is the default title.
+- `--title <text>` - plot title.
 
-- `--ylab YLAB` - Y axis title. The Y field name is the default title.
+- `--show-json` - show output in JSON format.
 
-- `--title TITLE` - plot title.
-
-- `-o, --stdout` - print plot content to stdout.
-
-- `--no-csv-header` - provided CSV or TSV datafile does not have a header.
+- `--no-csv-header` - lets DVC know that CSV or TSV `targets` do not have a
+  header.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -90,7 +86,7 @@ To visualize the difference between uncommitted changes of a metrics file and
 the last commit:
 
 ```dvc
-$ dvc plots diff -d logs.csv
+$ dvc plots diff --targets logs.csv
 file:///Users/dmitry/src/plots/logs.html
 ```
 
@@ -100,7 +96,7 @@ The difference between two versions (commit hashes, tags, or branches can be
 provided):
 
 ```dvc
-$ dvc plots diff -d logs.csv HEAD 0135527
+$ dvc plots diff --targets logs.csv HEAD 0135527
 file:///Users/usr/src/plots/logs.csv.html
 ```
 
@@ -130,7 +126,7 @@ A predefined confusion matrix
 separate plots:
 
 ```dvc
-$ dvc plots diff -t confusion -x predicted -d classes.csv
+$ dvc plots diff -t confusion -x predicted --targets classes.csv
 file:///Users/usr/src/test/plot_old/classes.csv.html
 ```
 

content/docs/command-reference/plots/index.md

@@ -1,7 +1,7 @@
 # plots
 
-Contains commands to visualize _plot metrics_ in structured files (JSON, CSV, or
-TSV): [show](/doc/command-reference/plots/show),
+A set of commands to visualize and compare _plot metrics_ in structured files
+(JSON, CSV, or TSV): [show](/doc/command-reference/plots/show),
 [diff](/doc/command-reference/plots/diff).
 
 ## Synopsis
@@ -11,10 +11,8 @@ usage: dvc plots [-h] [-q | -v] {show,diff} ...
 
 positional arguments:
   COMMAND
-    show         Generate a plot image file from a metrics file.
-    diff         Plot differences in metrics between commits in the
-                 DVC repository, or between the last commit and the
-                 workspace.
+    show         Generate plot from a metrics file.
+    diff         Plot differences in metrics between commits.
 ```
 
 ## Types of metrics

content/docs/command-reference/plots/show.md

@@ -1,58 +1,55 @@
 # plots show
 
-Generate a plot image from from a [plot metrics](/doc/command-reference/plots)
-file.
+Generate [plot](/doc/command-reference/plots) from a metrics file.
 
 ## Synopsis
 
 ```usage
-usage: dvc plots show [-h] [-q | -v] [-t [TEMPLATE]] [-f FILE]
-                     [-s SELECT] [-x X] [-y Y] [--stdout]
-                     [--no-csv-header] [--no-html] [--title TITLE]
-                     [--xlab XLAB] [--ylab YLAB] [datafile]
+usage: dvc plots show [-h] [-q | -v] [-t <path>] [-o <path>]
+                      [-x <field>] [-y <field>] [--no-csv-header]
+                      [--show-json] [--title <text>] [--xlab <text>]
+                      [--ylab <text>] targets [targets ...]
 
 positional arguments:
-  datafile              Metrics file to visualize
+  targets               Metrics files to visualize.
 ```
 
 ## Description
 
 This command provides a quick way to visualize metrics such as loss functions,
-AUC curves, confusion matrices, etc. Please see `dvc plots` for information on
-the supported data formats and other relevant details about DVC plots.
+AUC curves, confusion matrices, etc. One of more `targets` are required by this
+command as argument.
+
+Please see `dvc plots` for information on the supported data formats and other
+relevant details about DVC plots.
 
 ## Options
 
-- `-t [TEMPLATE], --template [TEMPLATE]` -
+- `-t <path>, --template <path>` -
   [plot template](/doc/command-reference/plots#plot-templates) to be injected
   with data. The default template is `.dvc/plots/default.json`. See more details
   in `dvc plots`.
 
-- `-f FILE, --file FILE` - name of the generated file. By default, the output
+- `-o <path>, --out <path>` - name of the generated file. By default, the output
   file name is equal to the input filename with additional `.html` suffix or
-  `.json` suffix for `--no-html` mode.
-
-- `--no-html` - do not wrap output Vega specification (JSON) with HTML.
-
-- `-x X` - field name for X axis. An auto-generated `index` field is used by
-  default.
+  `.json` suffix for `--show-json` mode.
 
-- `-y Y` - field name for Y axis. The last column or field found in the
-  `datafile` is used by default.
+- `-x <field>` - field name for X axis. An auto-generated `index` field is used
+  by default.
 
-- `-s SELECT, --select SELECT` - select which fields or JSONPath to store in the
-  metrics file [metadata](https://vega.github.io/vega/docs/data/). The
-  auto-generated, zero-based `index` column is always included.
+- `-y <field>` - field name for Y axis. The last column or field found in the
+  `targets` is used by default.
 
-- `--xlab XLAB` - X axis title. The X field name is the default title.
+- `--xlab <text>` - X axis title. The X field name is the default title.
 
-- `--ylab YLAB` - Y axis title. The Y field name is the default title.
+- `--ylab <text>` - Y axis title. The Y field name is the default title.
 
-- `--title TITLE` - plot title.
+- `--title <text>` - plot title.
 
-- `-o, --stdout` - print plot content to stdout.
+- `--show-json` - show output in JSON format.
 
-- `--no-csv-header` - provided CSV or TSV datafile does not have a header.
+- `--no-csv-header` - lets DVC know that CSV or TSV `targets` do not have a
+  header.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -128,11 +125,11 @@ file:///Users/usr/src/plots/logs.csv.html
 In many automation scenarios (like CI/CD for ML), it is convenient to have the
 [Vega-Lite](https://vega.github.io/vega-lite/) specification instead of the
 entire HTML plot file. For example to generating another image format like PNG
-or JPEG, or to include differently into a web app. The `--no-html` option
+or JPEG, or to include differently into a web app. The `--show-json` option
 prevents wrapping the plot in HTML. Note that the resulting file is JSON:
 
 ```dvc
-$ dvc plots show --select accuracy --no-html logs.csv
+$ dvc plots show --select accuracy --show-json logs.csv
 file:///Users/usr/src/plots/logs.csv.json
 ```
 

content/docs/command-reference/remote/add.md

@@ -93,7 +93,7 @@ The following are the types of remote storage (protocols) supported:
 $ dvc remote add myremote s3://bucket/path
 ```
 
-By default DVC expects your AWS CLI is already
+By default, DVC expects your 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, use the parameters described in `dvc remote modify`.
@@ -237,7 +237,7 @@ modified.
 $ dvc remote add myremote gs://bucket/path
 ```
 
-By default DVC expects your GCP CLI is already
+By default, DVC expects your GCP CLI is already
 [configured](https://cloud.google.com/sdk/docs/authorizing). DVC will be using
 default GCP key file to access Google Cloud Storage. To override some of these
 settings, use the parameters described in `dvc remote modify`.

content/docs/command-reference/remote/modify.md

@@ -78,7 +78,7 @@ The following are the customizable types of remote storage (protocols):
 
 ### Click for Amazon S3
 
-By default DVC expects your AWS CLI is already
+By default, DVC expects your 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 use the following options: