add docs for dvc metrics diff

public/static/docs/changelog/0.18.md

@@ -28,8 +28,8 @@ really excited to share the progress with you:
 - 🙂 **Usability improvements** - DVC interface got more informative and easier
   to use:
 
-  - More heavy operations render dynamic progress bar (e.g. hash computation):
-    ![](/static/img/0.18-progress.gif)
+  - More heavy operations render dynamic progress bar (e.g. file hash
+    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)

public/static/docs/command-reference/add.md

@@ -74,8 +74,8 @@ to work with directory hierarchies with `dvc add`:
    directory (with default name `dirname.dvc`). Every file in the hierarchy is
    added to the cache (unless `--no-commit` flag is added), but DVC does not
    produce individual DVC-files for each file in the directory tree. Instead,
-   the single DVC-file points to a file in the cache that contains references to
-   the files in the added hierarchy.
+   the single DVC-file references a file in the cache that in turn points to the
+   files in the added hierarchy.
 
 In a <abbr>DVC project</abbr>, `dvc add` can be used to version control any
 <abbr>data artifact</abbr> (input, intermediate, or output files and
@@ -197,8 +197,8 @@ Saving information to 'pics.dvc'.
 
 There are no [DVC-files](/doc/user-guide/dvc-file-format) generated within this
 directory structure, but the images are all added to the <abbr>cache</abbr>. DVC
-prints a message about this, mentioning that `md5` values are computed for each
-directory. A single `pics.dvc` DVC-file is generated for the top-level
+prints a message about this, mentioning that MD5 hash values are computed for
+each directory. A single `pics.dvc` DVC-file is generated for the top-level
 directory, and it contains:
 
 ```yaml

public/static/docs/command-reference/checkout.md

@@ -33,17 +33,17 @@ The execution of `dvc checkout` does the following:
 
 - Scans the DVC-files to compare against the data files or directories in the
   <abbr>workspace</abbr>. DVC knows which data (<abbr>outputs</abbr>) match
-  because their checksums are saved in the `outs` fields inside the DVC-files.
-  Scanning is limited to the given `targets` (if any). See also options
-  `--with-deps` and `--recursive` below.
+  because the corresponding file hash values are saved in the `outs` fields in
+  the DVC-files. Scanning is limited to the given `targets` (if any). See also
+  options `--with-deps` and `--recursive` below.
 
 - Missing data files or directories, or those that don't match with any
   DVC-file, are restored from the <abbr>cache</abbr>. See options `--force` and
   `--relink`.
 
-By default, this command tries not to copy files between the cache and the
-workspace, using reflinks instead, when supported by the file system. (Refer to
-[File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache).)
+By default, this command tries not make copies of cached files in the workspace,
+using reflinks instead when supported by the file system (refer to
+[File link types](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)).
 The next linking strategy default value is `copy` though, so unless other file
 link types are manually configured in `cache.type` (using `dvc config`), files
 will be copied. Keep in mind that having file copies doesn't present much of a
@@ -102,10 +102,9 @@ be pulled from remote storage using `dvc pull`.
 ## Examples
 
 Let's employ a simple <abbr>workspace</abbr> with some data, code, ML models,
-pipeline stages, as well as a few Git tags, such as our
-[get started example repo](https://github.com/iterative/example-get-started).
-Then we can see what happens with `git checkout` and `dvc checkout` as we switch
-from tag to tag.
+pipeline stages, such as the <abbr>DVC project</abbr> created in our
+[Get Started](/doc/get-started) section. Then we can see what happens with
+`git checkout` and `dvc checkout` as we switch from tag to tag.
 
 <details>
 
@@ -120,8 +119,7 @@ $ cd example-get-started
 
 </details>
 
-The workspace looks almost like in this
-[pipeline setup](/doc/tutorials/pipelines):
+The workspace looks something like this:
 
 ```dvc
 .
@@ -131,17 +129,19 @@ The workspace looks almost like in this
 ├── featurize.dvc
 ├── prepare.dvc
 ├── train.dvc
-└── src
-    └── <code files here>
+├── src
+│   └── ...
+└── train.dvc
 ```
 
-We have these tags in the repository that represent different iterations of
-solving the problem:
+This repository includes the following tags, that represent different variants
+of the resulting model:
 
 ```dvc
 $ git tag
-baseline-experiment     <- first simple version of the model
-bigrams-experiment      <- use bigrams to improve the model
+...
+baseline-experiment     <- First simple version of the model
+bigrams-experiment      <- Uses bigrams to improve the model
 ```
 
 This project comes with a predefined HTTP
@@ -153,57 +153,52 @@ files that are under DVC control. The model file checksum
 
 ```dvc
 $ dvc pull
-...
-Checking out model.pkl with cache '3863d0e317dee0a55c4e59d2ec0eef33'
-...
 
 $ md5 model.pkl
-MD5 (model.pkl) = 3863d0e317dee0a55c4e59d2ec0eef33
+MD5 (model.pkl) = 662eb7f64216d9c2c1088d0a5e2c6951
 ```
 
-What if we want to rewind history, so to speak? The `git checkout` command lets
-us checkout at any point in the commit history, or even checkout other tags. It
+What if we want to "rewind history", so to speak? The `git checkout` command
+lets us restore any point in the repository history, including any tags. It
 automatically adjusts the files, by replacing file content and adding or
 deleting files as necessary.
 
 ```dvc
-$ git checkout baseline
-Note: checking out 'baseline'.
-...
-HEAD is now at 40cc182...
+$ git checkout baseline-experiment  # Stage where model is first created
 ```
 
 Let's check the `model.pkl` entry in `train.dvc` now:
 
 ```yaml
 outs:
-  md5: a66489653d1b6a8ba989799367b32c43
-  path: model.pkl
+  - md5: 43630cce66a2432dcecddc9dd006d0a7
+    path: model.pkl
 ```
 
 But if you check `model.pkl`, the file hash is still the same:
 
 ```dvc
 $ md5 model.pkl
-MD5 (model.pkl) = 3863d0e317dee0a55c4e59d2ec0eef33
+MD5 (model.pkl) = 662eb7f64216d9c2c1088d0a5e2c6951
 ```
 
 This is because `git checkout` changed `featurize.dvc`, `train.dvc`, and other
 DVC-files. But it did nothing with the `model.pkl` and `matrix.pkl` files. Git
-doesn't track those files, DVC does, so we must do this:
+doesn't track those files; DVC does, so we must do this:
 
 ```dvc
 $ dvc fetch
 $ dvc checkout
+
 $ md5 model.pkl
-MD5 (model.pkl) = a66489653d1b6a8ba989799367b32c43
+MD5 (model.pkl) = 43630cce66a2432dcecddc9dd006d0a7
 ```
 
-What happened is that DVC went through the sole existing DVC-file and adjusted
-the current set of files to match the `outs` of that stage. `dvc fetch` is run
-once to download missing data from the remote storage to the <abbr>cache</abbr>.
-Alternatively, we could have just run `dvc pull` in this case to automatically
-do `dvc fetch` + `dvc checkout`.
+What happened is that DVC went through the DVC-files and adjusted the current
+set of files to match the `outs` in them. `dvc fetch` is run this once to
+download missing data from the remote storage to the <abbr>cache</abbr>.
+(Alternatively, we could have just run `dvc pull` to do `dvc fetch` +
+`dvc checkout` in one step.)
 
 ## Example: Automating DVC checkout
 
@@ -223,13 +218,10 @@ running `dvc checkout` when needed.
 again:
 
 ```dvc
-$ git checkout bigrams
-Previous HEAD position was d171a12 add evaluation stage
-HEAD is now at d092b42 try using bigrams
-Checking out model.pkl with cache '3863d0e317dee0a55c4e59d2ec0eef33'.
+$ git checkout bigrams-experiment  # Has the latest model version
 
 $ md5 model.pkl
-MD5 (model.pkl) = 3863d0e317dee0a55c4e59d2ec0eef33
+MD5 (model.pkl) = 662eb7f64216d9c2c1088d0a5e2c6951
 ```
 
 Previously this took two commands, `git checkout` followed by `dvc checkout`. We

public/static/docs/command-reference/config.md

@@ -115,9 +115,9 @@ for more details.) This section contains the following options:
 
   Due to the way DVC handles linking between the data files in the cache and
   their counterparts in the <abbr>workspace</abbr>, it's easy to accidentally
-  corrupt the cached version of a file by editing or overwriting it. Turning
-  this config option on forces you to run `dvc unprotect` before updating a
-  file, providing an additional layer of security to your data.
+  corrupt the cached file by editing or overwriting it. Turning this config
+  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
   `hardlink` or `symlink`.

public/static/docs/command-reference/diff.md

@@ -1,49 +1,41 @@
 # diff
 
-Show differences between two versions of the <abbr>DVC project</abbr>. It can be
-narrowed down to specific target files and directories under DVC control.
-
-> This command requires that the project is a [Git](https://git-scm.com/)
-> repository.
+Show changes between commits in the <abbr>DVC repository</abbr>, or between a
+commit and the <abbr>workspace</abbr>. The comparison can be narrowed down to
+specific target files/directories tracked by DVC.
 
 ## Synopsis
 
 ```usage
 usage: dvc diff [-h] [-q | -v] [-t TARGET] a_ref [b_ref]
 
 positional arguments:
-  a_ref      Git reference from which diff calculates
-  b_ref      Git reference until which diff calculates, if omitted diff
-             shows the difference between current HEAD and a_ref
+  a_rev                 Old Git commit to compare (defaults to HEAD)
+  b_rev                 New Git commit to compare (defaults to the
+                        current workspace)
 ```
 
 ## Description
 
-Given two Git commit references (commit hash, branch or tag name, etc) `a_ref`
-and `b_ref`, this command shows a comparative summary of basic statistics: how
-many files were deleted/changed, and the file size differences.
-
-> Note that `dvc diff` does not show the line-to-line comparison among the
-> target files in each revision, like `git diff` or
-> [GNU `diff`](https://www.gnu.org/software/diffutils/) can. This is because the
-> data data tracked by DVC can come in many possible formats e.g. structured
-> text, or binary blobs, etc.
+Given two commit SHA hashes, branch or tag names, etc.
+([references](https://git-scm.com/docs/revisions)) `a_ref` and `b_ref`, this
+command shows a comparative summary of basic statistics: how many files were
+deleted/changed, and the file size differences.
 
-> For an example on how to create line-to-line text file comparison, refer to
-> [issue #770](https://github.com/iterative/dvc/issues/770#issuecomment-512693256)
-> in our GitHub repository.
+> Note that `dvc diff` does not show the line-to-line comparisons like
+> `git diff` or [GNU `diff`](https://www.gnu.org/software/diffutils/) can. This
+> is because the data data tracked by DVC comes in many formats such as
+> structured text, binary blobs, etc. For an example on how to create
+> line-to-line text file comparison, refer to
+> [issue #770](https://github.com/iterative/dvc/issues/770#issuecomment-512693256).
 
-If the `-t` option is used, the diff is limited to the `TARGET` file or
-directory specified.
-
-Note that `dvc diff` does not have an effect when the repository is not tracked
-by the Git SCM, for example when `dvc init` was used with the `--no-scm` option.
+`dvc diff` does not have an effect when the repository is not tracked by Git,
+for example when `dvc init` was used with the `--no-scm` option.
 
 ## Options
 
-- `-t TARGET`, `--target TARGET` - path to a data file or directory. If not
-  specified, compares all files and directories that are under DVC control in
-  the workspace.
+- `-t TARGET`, `--target TARGET` - path to a data file or directory to limit
+  diff for.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -64,8 +56,9 @@ For these examples we can use the chapters in our
 
 Start by cloning our example repo if you don't already have it. Then move into
 the repo and checkout the
-[version](https://github.com/iterative/example-get-started/releases/tag/3-add-file)
-corresponding to the _Add Files_ chapter:
+[3-add-file](https://github.com/iterative/example-get-started/releases/tag/3-add-file)
+tag, corresponding to the [Add Files](/doc/get-started/add-files) _Get Started_
+chapter:
 
 ```dvc
 $ git clone https://github.com/iterative/example-get-started
@@ -83,13 +76,14 @@ Preparing to download data from 'https://remote.dvc.org/get-started'
 
 </details>
 
-## Example: Previous version of the same branch
+## Example: Previous commit in the same branch
+
+The minimal `dvc diff` command only includes the "from" reference (`a_ref`) from
+which to calculate the difference. The "until" reference (`b_ref`) defaults to
+`HEAD` (current Git commit).
 
-The minimal `dvc diff` command only includes the A reference (`a_ref`) from
-which the difference is to be calculated. The B reference (`b_ref`) defaults to
-Git `HEAD` (the currently checked out version). To find the general differences
-with the very previous committed version of the project, we can use the `HEAD^`
-Git reference.
+To see the difference with the very previous commit of the project, we can use
+`HEAD^` as `a_ref`:
 
 ```dvc
 $ dvc diff HEAD^
@@ -101,7 +95,7 @@ diff for 'data/data.xml'
 added file with size 37.9 MB
 ```
 
-## Example: Specific targets across Git references
+## Example: Specific targets across Git commits
 
 We can base this example in the [Metrics](/doc/get-started/metrics) and
 [Compare Experiments](/doc/get-started/compare-experiments) chapters of our _Get
@@ -131,8 +125,8 @@ example repo.
 
 </details>
 
-To see the difference in `model.pkl` among these versions, we can run the
-following command.
+To see the difference in `model.pkl` among these tags, we can run the following
+command.
 
 ```dvc
 $ dvc diff -t model.pkl baseline-experiment bigrams-experiment
@@ -145,7 +139,8 @@ diff for 'model.pkl'
 ```
 
 The output from this command confirms that there's a difference in the
-`model.pkl` file between the 2 Git references we indicated.
+`model.pkl` file between the 2 Git commits (tags `baseline-experiment` and
+`bigrams-experiment`) we indicated.
 
 ### What about directories?
 
@@ -193,6 +188,6 @@ diff for 'data/prepared'
 ```
 
 The command above checks whether there have been any changes to the
-`data/prepared` directory after the `5-preparation` version (since the `b_ref`
-is the current version, `HEAD` by default). The output tells us that there have
-been no changes to that directory (or to any other file).
+`data/prepared` directory after the `5-preparation` tag (since the `b_ref` is
+`HEAD` by default). The output tells us that there have been no changes to that
+directory (or to any other file).

public/static/docs/command-reference/fetch.md

@@ -94,10 +94,11 @@ specified in DVC-files currently in the project are considered by `dvc fetch`
   fetched. The default value is `4 * cpu_count()`. For SSH remotes default is
   just 4.
 
-- `-a`, `--all-branches` - fetch cache for all Git branches, not just the active
-  one. This means DVC may download files needed to reproduce different versions
-  of a DVC-file ([experiments](/doc/get-started/experiments)), not just the
-  current one.
+- `-a`, `--all-branches` - fetch cache for all Git branches instead of just the
+  current workspace. This means DVC may download files needed to reproduce
+  different versions of a DVC-file
+  ([experiments](/doc/get-started/experiments)), not just the ones currently in
+  the workspace.
 
 - `-T`, `--all-tags` - fetch cache for all Git tags. Similar to `-a` above. Note
   that both options can be combined, for example using the `-aT` flag.
@@ -115,9 +116,9 @@ specified in DVC-files currently in the project are considered by `dvc fetch`
 ## Examples
 
 Let's employ a simple <abbr>workspace</abbr> with some data, code, ML models,
-pipeline stages, as well as a few Git tags, such as our
-[get started example repo](https://github.com/iterative/example-get-started).
-Then we can see what happens with `dvc fetch` as we switch from tag to tag.
+pipeline stages, such as the <abbr>DVC project</abbr> created in our
+[Get Started](/doc/get-started) section. Then we can see what happens with
+`dvc fetch` as we switch from tag to tag.
 
 <details>
 
@@ -154,7 +155,7 @@ solving the problem:
 $ git tag
 
 baseline-experiment     <- first simple version of the model
-bigrams-experiment       <- use bigrams to improve the model
+bigrams-experiment      <- use bigrams to improve the model
 ```
 
 ## Example: Default behavior