cmd: document target granularity for push/pull/etc, et al.

content/docs/command-reference/add.md

@@ -59,12 +59,6 @@ Summarizing, the result is that the target data is replaced by small
 [`.dvc` files](/doc/user-guide/dvc-files-and-directories#dvc-files) that can be
 easily tracked with Git.
 
-> Note that `.dvc` files can be considered _orphan stages_, because they have no
-> <abbr>dependencies</abbr>, only outputs. These are treated as _always changed_
-> by `dvc status` and `dvc repro`, which always executes them. See
-> [`dvc.yaml`](/doc/user-guide/dvc-files-and-directories#dvcyaml-file) to learn
-> more about stages.
-
 To avoid adding files inside a directory accidentally, you can add the
 corresponding [patterns](/doc/user-guide/dvcignore) in a `.dvcignore` file.
 
@@ -87,9 +81,10 @@ in the directory tree. Instead, the single `.dvc` file references a special JSON
 file in the cache (with `.dir` extension), that in turn points to the added
 files.
 
-Note that DVC commands that use tracked files support granular targeting of
-files, even when the directory is added as a whole. Examples: `dvc push`,
-`dvc pull`, `dvc get`, `dvc import`, etc.
+Note that DVC commands that use tracked files or directories support targeting
+them granularly, even inside a directory that is
+[added as a whole](#example-directory). Examples: `dvc status`, `dvc push`,
+`dvc pull`, among others.
 
 As a rarely needed alternative, the `--recursive` option causes every file in
 the hierarchy to be added individually. A corresponding `.dvc` file will be

content/docs/command-reference/checkout.md

@@ -10,17 +10,17 @@ usage: dvc checkout [-h] [-q | -v] [--summary] [-d] [-R] [-f]
                     [--relink] [targets [targets ...]]
 
 positional arguments:
-  targets        Limit command scope to these stages or .dvc files.
-                 Using -R, directories to search for stages or .dvc
-                 files can also be given.
+  targets       Limit command scope to these tracked files/directories,
+                .dvc files, or stage names.
 ```
 
 ## Description
 
-`.dvc` and `dvc.lock` [files](/doc/user-guide/dvc-files-and-directories) act as
-pointers to specific version of data files or directories tracked by DVC. This
-command synchronizes the workspace data with the versions specified in the
-current `.dvc` and `dvc.lock` files.
+[`dvc.lock`](/doc/user-guide/dvc-files-and-directories#dvclock-file) and
+[`.dvc`](/doc/user-guide/dvc-files-and-directories#dvc-files) files act as
+pointers to the <abbr>cached</abbr> contents of data tracked by DVC. This
+command synchronizes the workspace data with the tracked file contents specified
+in the current `.dvc` and `dvc.lock` files.
 
 `dvc checkout` is useful, for example, when using Git in the
 <abbr>project</abbr>, after `git clone`, `git checkout`, or any other operation
@@ -33,15 +33,18 @@ for more details.
 
 The execution of `dvc checkout` does the following:
 
-- Scans the `.dvc` and `dvc.lock` files to compare against the data files or
-  directories in the <abbr>workspace</abbr>. DVC knows which data
-  (<abbr>outputs</abbr>) match because the corresponding hash values are saved
-  in the `outs` fields in those files. Scanning is limited to the given
+- Scans all `dvc.lock` and `.dvc` files to compare the hash values of its
+  <abbr>outputs</abbr> against the actual data files or directories in the
+  workspace (similar to `dvc status`). Scanning is limited to the given
   `targets` (if any). See also options `--with-deps` and `--recursive` below.
 
-- Missing data files or directories are restored from the <abbr>cache</abbr>.
-  Those that don't match with any DVC-file are removed. See options `--force`
-  and `--relink`. A list of the changes done is printed.
+- Missing data files or directories are restored from the cache. Those that
+  don't match with any DVC-file are removed. See options `--force` and
+  `--relink`. A list of the changes done is printed.
+
+> Note that `dvc checkout` supports granular targeting of files inside
+> directories that are
+> [tracked as a whole](/doc/command-reference/add#example-directory).
 
 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
@@ -130,9 +133,8 @@ below.
 
 The workspace looks like this:
 
-````dvc
+```dvc
 .
-├── README.md
 ├── data
 │   └── data.xml.dvc
 ├── dvc.lock
@@ -141,15 +143,11 @@ The workspace looks like this:
 ├── prc.json
 ├── scores.json
 └── src
-    ├── evaluate.py
-    ├── featurization.py
-    ├── prepare.py
-    ├── requirements.txt
-    └── train.py```
-````
+    └── <code files here>
+```
 
-This repository includes the following tags, that represent different variants
-of the resulting model:
+Note that this repository includes the following tags, that represent different
+variants of the resulting model:
 
 ```dvc
 $ git tag
@@ -158,10 +156,11 @@ baseline-experiment     <- First simple version of the model
 bigrams-experiment      <- Uses bigrams to improve the model
 ```
 
-We can now just run `dvc checkout` that will update the most recent `model.pkl`,
-`data.xml`, and other files that are tracked by DVC. The model file hash is
-defined in the `dvc.lock` file, and in the `data.xml.dvc` file for the
-`data.xml`:
+We can now run `dvc checkout` to update the most recent `model.pkl`, `data.xml`,
+and any other files tracked by DVC. The model file hash, `ab349c2...`, is saved
+in the
+[`dvc.lock` file](/doc/user-guide/dvc-files-and-directories#dvclock-file), for
+example, so it can be confirmed with:
 
 ```dvc
 $ dvc checkout
@@ -170,13 +169,15 @@ $ md5 model.pkl
 MD5 (data.xml) = ab349c2b5fa2a0f66d6f33f94424aebe
 ```
 
+## Example: Switch versions
+
 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.
+lets us restore any commit in the repository history (including tags). It
+automatically adjusts the repo files, by replacing, adding, or deleting them as
+necessary.
 
 ```dvc
-$ git checkout baseline-experiment  # Stage where model is first created
+$ git checkout baseline-experiment  # Commit where model was created
 ```
 
 Let's check the hash value of `model.pkl` in `dvc.lock` now:
@@ -187,16 +188,10 @@ outs:
     md5: 98af33933679a75c2a51b953d3ab50aa
 ```
 
-But if you check `model.pkl`, the file hash is still the same:
-
-```dvc
-$ md5 model.pkl
-MD5 (model.pkl) = ab349c2b5fa2a0f66d6f33f94424aebe
-```
-
-This is because `git checkout` changed `dvc.lock` 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:
+But if you check the MD5 of `model.pkl`, the file hash is still the same
+(`ab349c2...`). This is because `git checkout` changed `dvc.lock` and other DVC
+files, but it did nothing with `model.pkl`. Git doesn't track this file, DVC
+does, so we must do this instead:
 
 ```dvc
 $ dvc checkout
@@ -207,8 +202,29 @@ $ md5 model.pkl
 MD5 (model.pkl) = 98af33933679a75c2a51b953d3ab50aa
 ```
 
-What happened is that DVC went through the DVC-files and adjusted the current
-set of <abbr>output</abbr> files to match the `outs` in them.
+DVC went through `dvc.lock` and adjusted the current set of <abbr>outputs</abbr>
+to match the `outs` in it.
+
+## Example: Specific files or directories
+
+`dvc checkout` only affects the tracked data corresponding to any given
+`targets`:
+
+```dvc
+$ git checkout master
+$ dvc checkout            # Start with latest version of everything.
+
+$ git checkout baseline-experiment -- dvc.lock
+$ dvc checkout model.pkl  # Get previous model file only.
+```
+
+Note that `dvc checkout` supports granular targeting of files inside directories
+that are tracked as a whole. For example, the `featurize` stage has a directory
+output (`data/features`) and we can do:
+
+```dvc
+$ dvc checkout data/features/test.pkl
+```
 
 ## Example: Automating DVC checkout