cmd ref: add checkout --relink option, improve checkout desc.

static/docs/command-reference/checkout.md

@@ -6,7 +6,7 @@ DVC-files.
 ## Synopsis
 
 ```usage
-usage: dvc checkout [-h] [-q | -v] [-d] [-f] [-R]
+usage: dvc checkout [-h] [-q | -v] [-d] [-R] [-f] [--relink]
                     [targets [targets ...]]
 
 positional arguments:
@@ -16,60 +16,49 @@ positional arguments:
 
 ## Description
 
-[DVC-files](/doc/user-guide/dvc-file-format) in a <abbr>project</abbr> specify
-which instance of each data file or directory should be used, with the checksums
-saved in the `outs` field. The `dvc checkout` command updates the workspace data
-to match with the <abbr>cached</abbr> files that correspond to those checksums.
-
-Using an SCM like Git, the DVC-files are kept under version control. At a given
-branch or tag of the SCM repository, the DVC-files will contain checksums for
-the corresponding data files kept in the cache. After an SCM command like
-`git checkout` is run, the DVC-files will change to the state at the specified
-branch or commit or tag. Afterwards, the `dvc checkout` command is required in
-order to synchronize the data files with the currently checked out DVC-files.
-
-This command must be executed after `git checkout` since Git doesn't track files
-that are under DVC control. For convenience a Git hook is available, simply by
-running `dvc install`, that will automate running `dvc checkout` after
-`git checkout`. See `dvc install` for more information.
-
-The execution of `dvc checkout` does:
-
-- Scan the `outs` entries in DVC-files to compare with the currently checked out
-  data files. The scanned DVC-files is limited by the listed `targets` (if any)
-  on the command line. And if the `--with-deps` option is specified, it scans
-  backward from the given `targets` in the corresponding
-  [pipeline](/doc/command-reference/pipeline).
-
-- For any data files where the checksum doesn't match their DVC-file entry, the
-  data file is restored from the cache. The link strategy used (`reflink`,
-  `hardlink`, `symlink`, or `copy`) depends on the OS and the configured value
-  for `cache.type` – See `dvc config cache`.
-
-Note that this command by default tries NOT to copy files between the cache and
-the workspace, using reflinks instead when supported by the file system. (Refer
-to
+[DVC-files](/doc/user-guide/dvc-file-format) are essentially placeholders that
+point to the actual data files or a directories under DVC control. This command
+synchronizes the workspace data with the versions specified in the current
+DVC-files. DVC knows which data files (<abbr>outputs</abbr>) to use because
+their checksums are saved in the `outs` fields inside the DVC-files.
+
+`dvc checkout` is useful when using Git in the <abbr>project</abbr>, after
+`git clone`, `git checkout`, or any other repository operations that change the
+currently present DVC-files.
+
+💡 For convenience, a Git hook is available to automate running `dvc checkout`
+after `git checkout`. Use `dvc install` to install it.
+
+The execution of `dvc checkout` does the following:
+
+- Scans the DVC-files to compare vs. the data files or directories currently in
+  the <abbr>workspace</abbr>. 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).)
 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
 negative impact unless the project uses very large data (several GBs or more).
-But leveraging file links is crucial for large files where checking out a 50Gb
-by copying file might take a few minutes for example, whereas with links,
+But leveraging file links is crucial with large files, for example when checking
+out a 50Gb file by copying might take a few minutes whereas, with links,
 restoring any file size will be almost instantaneous.
 
 > When linking files takes longer than expected (10 seconds for any one file)
 > and `cache.type` is not set, a warning will be displayed reminding users about
 > the faster link types available. These warnings can be turned off setting the
 > `cache.slow_link_warning` config option to `false` with `dvc config cache`.
 
-The output of `dvc checkout` does not list which data files were restored. It
-does report removed files and files that DVC was unable to restore because
-they're missing from the <abbr>cache</abbr>.
-
 This command will fail to checkout files that are missing from the cache. In
-such a case, `dvc checkout` prints a warning message. Any files that can be
-checked out without error will be restored.
+such a case, `dvc checkout` prints a warning message. It also lists removed
+files. Any files that can be checked out without error will be restored without
+being reported individually.
 
 There are two methods to restore a file missing from the cache, depending on the
 situation. In some cases a pipeline must be reproduced (using `dvc repro`) to
@@ -94,6 +83,13 @@ be pulled from remote storage using `dvc pull`.
   remove files that don't match those DVC-file references or are missing from
   cache. (They are not "committed", in DVC terms.)
 
+- `--relink` - ensures the file linking strategy (`reflink`, `hardlink`,
+  `symlink`, or `copy`) for all data files in the workspace is consistent with
+  the project's [`cache.type`](/doc/command-reference/config#cache). This is
+  achieved by restoring **all data files or a directories** referenced in
+  current DVC-files (regardless of whether they match a current DVC-file). This
+  means overwriting the file links or copies from cache to workspace.
+
 - `-h`, `--help` - shows the help message and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

static/docs/command-reference/config.md

@@ -139,6 +139,10 @@ for more details.) This section contains the following options:
   [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.
+
 - `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`
   when linking files takes longer than usual, to remind them that there are

static/docs/understanding-dvc/related-technologies.md

@@ -100,11 +100,11 @@ http://studio.ml/
 - Git-annex is a datafile-centric system whereas DVC is focused on providing a
   workflow for machine learning and reproducible experiments. When a DVC or
   Git-annex repository is cloned via `git clone`, data files won't be copied to
-  the local machine as file contents are stored in separate
+  the local machine, as file contents are stored in separate
   [remotes](/doc/command-reference/remote). With DVC,
-  [DVC-files](/doc/user-guide/dvc-file-format) (that provide the reproducible
-  workflow) are always included in the Git repository and hence can be recreated
-  locally with minimal effort.
+  [DVC-files](/doc/user-guide/dvc-file-format), which provide the reproducible
+  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.

static/docs/user-guide/large-dataset-optimization.md

@@ -38,11 +38,11 @@ Symbolic links, and Reflinks in more recent systems. While reflinks bring all
 the benefits and none of the worries, they're not commonly supported in most
 platforms yet. Hard/soft links optimize **speed** and **space** in the file
 system, but may break your workflow since updating hard/sym-linked files tracked
-by DVC in the workspace causes <abbr>cache</abbr> 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 inefficient – especially for
-large files (several GBs or more).
+by DVC in the <abbr>workspace</abbr> causes <abbr>cache</abbr> 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
+inefficient – especially for large files (several GBs or more).
 
 > Some versions of Windows (e.g. Windows Server 2012+ and Windows 10 Enterprise)
 > support hard or soft links on the
@@ -92,9 +92,9 @@ efficiency:
 
 4. **`copy`**: An inefficient "linking" strategy, yet supported on all file
    systems. Using `copy` means there will be no file links, but that the tracked
-   files will be duplicated as copies existing in both the cache and workspace.
-   Suitable for scenarios with relatively small data files, where copying them
-   is not a storage performance concern.
+   files will be duplicated as copies existing in both the cache and
+   <abbr>workspace</abbr>. Suitable for scenarios with relatively small data
+   files, where copying them is not a storage performance concern.
 
 > DVC avoids `symlink` and `hardlink` types by default to protect user from
 > accidental cache corruption. Refer to the
@@ -120,6 +120,13 @@ file link types. Please refer to the
 [Update a Tracked File](/doc/user-guide/updating-tracked-files) on how to manage
 tracked files under these cache configurations.
 
+### Re-linking data in the workspace
+
+To re-create the file links in the workspace, for example after changing the
+`cache.type` option for a <abbr>project</abbr>, please use
+`dvc checkout --relink`. See
+[checkout options](/doc/command-reference/checkout#options) for more details.
+
 ---
 
 > \***copy-on-write links or "reflinks"** are a relatively new way to link files