Misc. updates

content/docs/command-reference/fetch.md

@@ -1,7 +1,7 @@
 # fetch
 
-Get tracked files or directories from
-[remote storage](/doc/command-reference/remote) into the <abbr>cache</abbr>.
+Download files or directories from
+[remote storage](/doc/command-reference/remote) to the <abbr>cache</abbr>.
 
 ## Synopsis
 
@@ -17,22 +17,12 @@ positional arguments:
 
 ## Description
 
-Downloads DVC-tracked files from remote storage into the cache of the project
-(without placing them in the <abbr>workspace</abbr>, like `dvc pull` would).
-This makes them available for linking (or copying) into the workspace (refer to
-[`dvc config cache.type`](/doc/command-reference/config#cache)).
+Downloads tracked files and directories from remote storage into the
+<abbr>cache</abbr> (without placing them in the <abbr>workspace</abbr> like
+`dvc pull`). This makes the tracked data available for linking (or copying) into
+the workspace (see `dvc checkout`).
 
-Without arguments, `dvc fetch` ensures that the files specified in all
-`dvc.lock` and `.dvc` files in the workspace exist in the cache. The
-`--all-branches`, `--all-tags`, and `--all-commits` options enable fetching data
-for multiple Git commits.
-
-The `targets` given to this command (if any) limit what to fetch. It accepts
-paths to tracked files or directories (including paths inside tracked
-directories), `.dvc` files, and stage names (found in `dvc.yaml`).
-
-Fetching is performed automatically by `dvc pull` (when the data is not already
-in the <abbr>cache</abbr>), along with `dvc checkout`:
+Note that `dvc pull` already includes fetching:
 
 ```
 Tracked files                Commands
@@ -56,14 +46,23 @@ Here are some scenarios in which `dvc fetch` is useful, instead of pulling:
 - After checking out a fresh copy of a <abbr>DVC repository</abbr>, to get
   DVC-tracked data from multiple project branches or tags into your machine.
 - To use comparison commands across different Git commits, for example
-  `dvc metrics show` with its `--all-branches` option.
+  `dvc metrics show` with its `--all-branches` option, or `dvc plots diff`.
 - If you want to avoid [linking](/doc/user-guide/large-dataset-optimization)
   files from the cache, or keep the <abbr>workspace</abbr> clean for any other
   reason.
 
+Without arguments, it downloads all files and directories referenced in the
+current workspace (found in `dvc.yaml` and `.dvc` files) that are missing from
+the workspace. Any `targets` given to this command limit what to fetch. It
+accepts paths to tracked files or directories (including paths inside tracked
+directories), `.dvc` files, and stage names (found in `dvc.yaml`).
+
+The `--all-branches`, `--all-tags`, and `--all-commits` options enable fetching
+files/dirs referenced in multiple Git commits.
+
 The default remote is used (see
-[`dvc config core.remote`](/doc/command-reference/config#core)) unless the
-`--remote` option is used.
+[`dvc config core.remote`](/doc/command-reference/config#core)) unless a
+specific one is given with `--remote`.
 
 ## Options
 
@@ -173,18 +172,15 @@ $ tree .dvc/cache
 > `dvc status --cloud` compares the cache contents against the default remote.
 > Refer to `dvc status`.
 
-Note that the `.dvc/cache` directory was created and populated.
-
-> Refer to
-> [Structure of cache directory](/doc/user-guide/dvc-files-and-directories#structure-of-the-cache-directory)
-> for more info.
+Note that the
+[`.dvc/cache`](/doc/user-guide/dvc-files-and-directories#structure-of-the-cache-directory)
+directory was created and populated.
 
-Used without arguments (as above), `dvc fetch` downloads all files and
-directories needed by all `dvc.yaml` and `.dvc` files in the current branch. For
-example, the hash values `20b786b...` and `c8d307a...` correspond to the
-`data/features/` directory and `model.pkl` file, respectively.
+All the data needed in this version of the project is now in your cache: File
+names `20b786b...` and `c8d307a...` correspond to the `data/features/` directory
+and `model.pkl` file, respectively.
 
-Let's now link files from the cache to the workspace with:
+To link these files to the workspace:
 
 ```dvc
 $ dvc checkout

content/docs/command-reference/freeze.md

@@ -24,7 +24,7 @@ Freezing a stage is useful to avoid syncing data from the top of its
 (non-frozen) stages only.
 
 Note that <abbr>import stages</abbr> are frozen by default. Use `dvc update` to
-update the imported data from the external data source.
+bring the import up to date from the data source.
 [Unfreeze](/doc/command-reference/unfreeze) them before using `dvc repro` on a
 pipeline that needs their outputs.
 

content/docs/command-reference/import-url.md

@@ -51,8 +51,7 @@ enough metadata about the imported data to enable DVC efficiently determining
 whether the local copy is out of date.
 
 Note that `dvc repro` doesn't check or update import `.dvc` files, use
-`dvc update` on them to bring the import up to date from the external data
-source.
+`dvc update` to bring the import up to date from the data source.
 
 DVC supports several types of (local or) remote locations (protocols):
 
@@ -125,10 +124,9 @@ source.
   default file name: `<file>.dvc`, where `<file>` is the desired file name of
   the imported data (`out`).
 
-- `--no-exec` - create the import `.dvc` file without actually downloading
-  `url`. The data hash is not calculated when this option is used, only the
-  import metadata is saved to the `.dvc` file. You can use `dvc commit` to
-  finish the operation.
+- `--no-exec` - create the import `.dvc` file but don't download `url` (assumes
+  that the data source is valid). You can use `dvc commit` to finish the
+  operation.
 
   This is useful, for example, if you need to define a project quickly (that
   will use imports at a later time/location) before downloading anything, and

content/docs/command-reference/import.md

@@ -24,8 +24,8 @@ positional arguments:
 
 Provides an easy way to reuse files or directories tracked in any <abbr>DVC
 repository</abbr> (e.g. datasets, intermediate results, ML models) or Git
-repository (e.g. source code, small image/other files). `dvc import` downloads
-the target file or directory (found at `path` in `url`) into the workspace and
+repository (e.g. code, small image/other files). `dvc import` downloads the
+target file or directory (found at `path` in `url`) into the workspace and
 tracks it in the project. This makes it possible to update the import later, if
 it has changed in its data source (see `dvc update`).
 
@@ -73,10 +73,9 @@ source.
 To actually [version the data](/doc/tutorials/get-started/data-versioning),
 `git add` (and `git commit`) the import stage.
 
-Note that import stages are considered always
-[frozen](/doc/command-reference/freeze), meaning that if you run `dvc repro`,
-they won't be updated. Use `dvc update` to update the downloaded data artifact
-from the source repo.
+Note that `dvc repro` doesn't check or update import `.dvc` files (see
+`dvc freeze`), use `dvc update` to bring the import up to date from the data
+source.
 
 Also note that chained imports (importing data that was imported into the source
 repo at `url`) are not supported.
@@ -103,10 +102,9 @@ repo at `url`) are not supported.
   > [Importing and updating fixed revisions](#example-importing-and-updating-fixed-revisions)
   > example below).
 
-- `--no-exec` - create the import `.dvc` file without actually downloading the
-  file or directory. The data hash is not calculated when this option is used,
-  only the import metadata is saved to the `.dvc` file. You can use `dvc commit`
-  to finish the operation.
+- `--no-exec` - create the import `.dvc` file but don't download the target data
+  (doesn't check whether the source is valid). You can use `dvc commit` to
+  finish the operation.
 
   This is useful, for example, if you need to define a project quickly (that
   will use imports at a later time/location) before downloading anything, and

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

@@ -25,7 +25,7 @@ project params.
 > Parameter dependencies are defined with the `-p` option in `dvc run`. See also
 > `dvc params`.
 
-Run without arguments, this command compares parameters currently present in the
+Without arguments, this command compares parameters currently present in the
 <abbr>workspace</abbr> (uncommitted changes) with the latest committed version.
 
 Supported parameter _value_ types are: string, integer, float, and arrays. DVC

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

@@ -36,9 +36,9 @@ please see `dvc plots`.
 
 ## Options
 
-- `-o <path>, --out <path>` - name of the generated file. By default, the output
-  file name is equal to the input filename with a `.html` file extension (or
-  `.json` when using `--show-vega`).
+- `-o <path>, --out <path>` - name of the generated file. By default, this file
+  name is equal to the input filename with a `.html` file extension (or `.json`
+  when using `--show-vega`).
 
 - `-t <name_or_path>, --template <name_or_path>` -
   [plot template](/doc/command-reference/plots#plot-templates) to be injected

content/docs/command-reference/pull.md

@@ -53,19 +53,18 @@ project's cache                  ++ | dvc pull |
  workspace
 ```
 
-The default remote is used (see `dvc remote default`) unless the `--remote`
-option is used. See `dvc remote` for more information on how to configure a
-remote.
+The default remote is used (see `dvc remote default`) unless a specific one is
+given with `--remote`. See `dvc remote` for more information on how to configure
+a remote.
+
+Without arguments, it downloads all files and directories referenced in the
+current workspace (found in `dvc.yaml` and `.dvc` files) that are missing from
+the workspace. Any `targets` given to this command limit what to pull. It
+accepts paths to tracked files or directories (including paths inside tracked
+directories), `.dvc` files, and stage names (found in `dvc.yaml`).
 
-Without arguments, it downloads all files and directories missing from the
-project, found as <abbr>outputs</abbr> of the
-[stages](/doc/command-reference/run) or `.dvc` files present in the workspace.
 The `--all-branches`, `--all-tags`, and `--all-commits` options enable pulling
-multiple Git commits.
-
-The `targets` given to this command (if any) limit what to pull. It accepts
-paths to tracked files or directories (including paths inside tracked
-directories), `.dvc` files, and stage names (found in `dvc.yaml`).
+files/dirs referenced in multiple Git commits.
 
 After the data is in the <abbr>cache</abbr>, `dvc pull` uses OS-specific
 mechanisms like reflinks or hardlinks to put it in the workspace, trying to
@@ -175,7 +174,7 @@ $ tree
 └── model.pkl
 ```
 
-We can download specific <abbr>outputs</abbr> of a single stage:
+We can also download only the <abbr>outputs</abbr> of a specific stage:
 
 ```dvc
 $ dvc pull train

content/docs/command-reference/push.md

@@ -32,19 +32,18 @@ use cases for these commands.
 > Note that pushing data does not affect code, `dvc.yaml`, or `.dvc` files.
 > Those should be uploaded with `git push`.
 
-The default remote is used (see `dvc remote default`) unless the `--remote`
-option is used. See `dvc remote` for more information on how to configure a
-remote.
+The default remote is used (see `dvc remote default`) unless a specific one is
+given with `--remote`. See `dvc remote` for more information on how to configure
+them.
+
+Without arguments, it uploads the files and directories referenced in the
+current workspace (found in all `dvc.yaml` and `.dvc` files) that are missing
+from the remote. Any `targets` given to this command limit what to push. It
+accepts paths to tracked files or directories (including paths inside tracked
+directories), `.dvc` files, and stage names (found in `dvc.yaml`).
 
-Without arguments, it uploads all files and directories missing from remote
-storage, found as <abbr>outputs</abbr> of the
-[stages](/doc/command-reference/run) or `.dvc` files present in the workspace.
 The `--all-branches`, `--all-tags`, and `--all-commits` options enable pushing
-multiple Git commits.
-
-The `targets` given to this command (if any) limit what to push. It accepts
-paths to tracked files or directories (including paths inside tracked
-directories), `.dvc` files, and stage names (found in `dvc.yaml`).
+files/dirs referenced in multiple Git commits.
 
 💡 For convenience, a Git hook is available to automate running `dvc push` after
 `git push`. See `dvc install` for more details.
@@ -86,7 +85,7 @@ in the cache (compared to the default remote.) It can be used to see what files
   If there are no directories among the `targets`, this option is ignored.
 
 - `-r <name>`, `--remote <name>` - name of the
-  [remote storage](/doc/command-reference/remote) to push from (see
+  [remote storage](/doc/command-reference/remote) to push to (see
   `dvc remote list`).
 
 - `--run-cache` - uploads all available history of stage runs to the remote

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

@@ -100,6 +100,14 @@ url = /path/to/remote
 remote = myremote
 ```
 
+## Example: List all remotes in the project
+
+```dvc
+$ dvc remote list
+myremote	/path/to/remote
+newremote	s3://mybucket/path
+```
+
 ## Example: Customize an additional S3 remote
 
 > 💡 Before adding an S3 remote, be sure to
@@ -122,18 +130,10 @@ url = s3://mybucket/path
 endpointurl = https://object-storage.example.com
 ```
 
-## Example: List all remotes in the project
-
-```dvc
-$ dvc remote list
-myremote	/path/to/remote
-newremote	s3://mybucket/path
-```
-
 ## Example: Change the name of a remote
 
-Notice that `dvc remote modify` doesn't provide a way to change the name of a
-DVC remote, but there's a specific subcommand for this:
+`dvc remote modify` can't change the name of a DVC remote, but there's a
+specific subcommand for this:
 
 ```dvc
 $ dvc remote rename newremote oldremote

content/docs/command-reference/run.md

@@ -228,14 +228,13 @@ $ dvc run -n my_stage './my_script.sh $MYENVVAR'
   It's used by `dvc repro` to change the working directory before executing the
   `command`.
 
-- `--no-exec` - write the stage to `dvc.yaml`, but do not execute its `command`.
-  Any dependencies and outputs will be entered in `.gitignore`, but won't be
-  cached (like with `--no-commit` below) or recorded in `dvc.lock`. You can use
-  `dvc commit` to save any existing dep/out files to the cache and record their
-  hashes to the lock file.
+- `--no-exec` - write the stage to `dvc.yaml`, but do not execute the `command`.
+  DVC will still add the outputs to `.gitignore`, but they won't be cached or
+  recorded in `dvc.lock` (like with `--no-commit` below). You can use
+  `dvc commit` to finish the operation.
 
   This is useful, for example, if you need to define a pipeline quickly (and
-  perhaps share it with others) before executing anything, and run all its
+  perhaps share it with others) before executing anything, and run all of its
   stages at once later (with `dvc repro`).
 
 - `-f`, `--force` - overwrite an existing stage in `dvc.yaml` file without

content/docs/command-reference/status.md

@@ -32,16 +32,16 @@ _remote_ mode is triggered by using the `--cloud` or `--remote` options:
 | 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`).             |
 
-Without arguments, this command checks all stages (defined in `dvc.yaml`) and
-`.dvc` files, and compares the hash values of their <abbr>outputs</abbr> (found
-in `dvc.lock` for stages) against the actual data files or directories in the
-workspace. The `--all-branches`, `--all-tags`, and `--all-commits` options
-enable checking data for multiple Git commits.
-
-The `targets` given to this command (if any) limit what to check. It accepts
-paths to tracked files or directories (including paths inside tracked
+Without arguments, it checks all `dvc.yaml` and `.dvc` files, and compares their
+<abbr>outputs</abbr> against the actual data files or directories in the
+workspace. Any `targets` given to this command limit what to show changes for.
+It accepts paths to tracked files or directories (including paths inside tracked
 directories), `.dvc` files, and stage names (found in `dvc.yaml`).
 
+The `--all-branches`, `--all-tags`, and `--all-commits` options enable comparing
+[metafiles](/doc/user-guide/dvc-files-and-directories) referenced in multiple
+Git commits at once.
+
 If no differences are detected, `dvc status` prints
 `Data and pipelines are up to date.` or
 `Cache and remote 'myremote' are in sync` (if using the `-c` or `-r` options are
@@ -117,27 +117,28 @@ that.
   the workspace. Note that both options can be combined, for example using the
   `-aT` flag.
 
+- `--all-commits` - same as `-a` or `-T` above, but applies to _all_ Git commits
+  as well as the workspace. This compares the cache content for the entire
+  commit history of the project.
+
 - `-R`, `--recursive` - determines the files to check status for by searching
   each target directory and its subdirectories for stages (in `dvc.yaml`) and
   `.dvc` files to inspect. If there are no directories among the targets, this
   option is ignored.
 
-- `--show-json` - prints the command's output in easily parsable JSON format,
-  instead of a human-readable table.
-
-- `--all-commits` - same as `-a` or `-T` above, but applies to _all_ Git commits
-  as well as the workspace. This compares the cache content for the entire
-  commit history of the project.
-
 - `-d`, `--with-deps` - determines files to check by tracking dependencies to
   the `targets`. If none are provided, this option is ignored. By traversing all
   stage dependencies, DVC searches backward from the target stages in the
   corresponding pipelines. This means DVC will not show changes occurring in
   later stages than the `targets`. Applies whether or not `--cloud` is
   specified.
 
-- `-r <name>`, `--remote <name>` - specifies which remote storage (see
-  `dvc remote list`) to compare against. Implies `--cloud`.
+- `-r <name>`, `--remote <name>` - name of the
+  [remote storage](/doc/command-reference/remote) to compare against (see
+  `dvc remote list`. Implies `--cloud`.
+
+- `--show-json` - prints the command's output in easily parsable JSON format,
+  instead of a human-readable table.
 
 - `-j <number>`, `--jobs <number>` - parallelism level for DVC to retrieve
   information from remote storage. This only applies when the `--cloud` option

content/docs/index.md

@@ -1,6 +1,6 @@
 # DVC Documentation
 
-Data Version Control, or DVC, is a data and ML experiments management tool that
+Data Version Control, or DVC, is a data and ML experiment management tool that
 takes advantage of the existing engineering toolset that you're already familiar
 with (Git, CI/CD, etc.).
 

content/docs/user-guide/basic-concepts/dvc-cache.md

@@ -1,6 +1,6 @@
 ---
 name: 'DVC Cache'
-match: ['DVC cache', cache, caches, cached]
+match: ['DVC cache', cache, caches, cached, 'cache directory']
 ---
 
 The DVC cache is a hidden storage (by default located in the `.dvc/cache`