cmd ref: review option defaults and sentence priority per API params

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

@@ -89,10 +89,9 @@ reproducible.
 ## Options
 
 - `-R`, `--recursive` - determines the files to add by searching each target
-  directory and its subdirectories for data files. For each file found, a new
+  directory and its subdirectories for data files. If there are no directories
+  among the `targets`, this option is ignored. For each file found, a new
   DVC-file is created using the process described in this command's description.
-  `targets` is expected to contain one or more directories for this option to
-  have effect.
 
 - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an
   entry is added to `.dvc/state`, while nothing is added to the cache. (The
@@ -107,11 +106,11 @@ reproducible.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-- `-f`, `--file` - specify name of the DVC-file it generates. This option works
-  only if there is a single target. By default the name of the generated
-  DVC-file is `<target>.dvc`, where `<target>` is the file name of the given
-  target. This option allows to set the name and the path of the generated
-  DVC-file.
+- `-f`, `--file` - specify name of the DVC-file it generates. If more than a
+  single target are provided, this option is ignored. By default, the name of
+  the generated DVC-file is `<target>.dvc`, where `<target>` is the file name of
+  the given target. This option allows to set the name and the path of the
+  generated DVC-file.
 
 ## Example: Single file
 

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

@@ -69,16 +69,15 @@ be pulled from remote storage using `dvc pull`.
 
 ## Options
 
-- `-d`, `--with-deps` - one or more `targets` should be specified for this
-  option to have effect. Determines files to update by tracking dependencies to
-  the target DVC-files (stages). By traversing all stage dependencies, DVC
-  searches backward from the target stages in the corresponding pipelines. This
-  means DVC will not checkout files referenced in later stages than the
-  `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain one or more directories
-  for this option to have effect. Determines the files to checkout by searching
-  each target directory and its subdirectories for DVC-files to inspect.
+- `-d`, `--with-deps` - determines files to update by tracking dependencies to
+  the target DVC-files (stages). If no `targets` 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 checkout
+  files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - determines the files to checkout by searching each
+  target directory and its subdirectories for DVC-files to inspect. If there are
+  no directories among the `targets`, this option is ignored.
 
 - `-f`, `--force` - does not prompt when removing workspace files. Changing the
   current set of DVC-files with `git checkout` can result in the need for DVC to

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

@@ -71,15 +71,15 @@ reproducibility in those cases.
 
 ## Options
 
-- `-d`, `--with-deps` - one or more `targets` should be specified for this
-  option to have effect. Determines files to commit by tracking dependencies to
-  the target DVC-files (stages). By traversing all stage dependencies, DVC
-  searches backward from the target stages in the corresponding pipelines. This
-  means DVC will not commit files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain one or more directories
-  for this option to have effect. Determines the files to commit by searching
-  each target directory and its subdirectories for DVC-files to inspect.
+- `-d`, `--with-deps` - determines files to commit by tracking dependencies to
+  the target DVC-files (stages). If no `targets` 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 commit
+  files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - determines the files to commit by searching each target
+  directory and its subdirectories for DVC-files to inspect. If there are no
+  directories among the `targets`, this option is ignored.
 
 - `-f`, `--force` - commit data even if hash values for dependencies or outputs
   did not change.

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

@@ -65,11 +65,11 @@ This is the main section with the general config options:
 - `core.loglevel` - log level that the `dvc` command should use. Possible values
   are: `info`, `debug`, `warning`, `error`.
 
-- `core.remote` - name of the remote that should be used by default.
+- `core.remote` - name of the remote storage that should be used by default.
 
 - `core.interactive` - whether to always ask for confirmation before reproducing
-  each [stage](/doc/command-reference/run) in `dvc repro`. By default this
-  behavior requires the use of option `-i` in that command. Accepts values
+  each [stage](/doc/command-reference/run) in `dvc repro`. (Normally, this
+  behavior requires the use of option `-i` in that command.) Accepts values
   `true` and `false`.
 
 - `core.analytics` - used to turn off
@@ -102,8 +102,8 @@ for more details.) This section contains the following options:
 
 - `cache.dir` - set/unset cache directory location. A correct value must be
   either an absolute path or a path **relative to the config file location**.
-  The default value is `cache` that, resolved relative to the default project
-  config location, results in `.dvc/cache`.
+  The default value is `cache`, that resolves to `.dvc/cache` (relative to the
+  project config file location).
 
   > See also helper command `dvc cache dir` to intuitively set this config
   > option, properly transforming paths relative to the current working
@@ -153,10 +153,10 @@ for more details.) This section contains the following options:
   > set.
 
 - `cache.shared` - permissions for newly created or downloaded cache files and
-  directories. The default permissions are `0o664`(rw-r--r--) for files and
-  `0o755`(rwxr-xr-x) for directories. The only accepted value right now is
-  `group`, which makes DVC use `0o664`(rw-rw-r--) for files and
-  `0o775`(rwxrwxr-x) for directories, which is useful when you are using a a
+  directories. The default is `0o664`(rw-r--r--) for files and `0o755`
+  (rwxr-xr-x) for directories. The only accepted value right now is `group`,
+  which makes DVC use `0o664` (rw-rw-r--) for files and `0o775` (rwxrwxr-x) for
+  directories, which is useful when you are using a a
   [shared development server](/doc/use-cases/shared-development-server).
 
 - `cache.local` - name of a local remote to use as cache directory. (Refer to
@@ -191,15 +191,15 @@ learn more about the state file (database) that is used for optimization.
 
 - `state.row_limit` - maximum number of entries in the state database, which
   affects the physical size of the state file itself, as well as the performance
-  of certain DVC operations. The bigger the limit, the longer the file hash
-  history that DVC can keep, in order to avoid sequential hash recalculations.
-  The default limit is set to 10,000,000 rows.
+  of certain DVC operations. The default is 10,000,000 rows. The bigger the
+  limit, the longer the file hash history that DVC can keep, in order to avoid
+  sequential hash recalculations.
 
 - `state.row_cleanup_quota` - percentage of the state database that is going to
-  be deleted when it hits the `state.row_limit`. When an entry in the database
-  is used (e.g. during the `dvc status`) dvc updates the timestamp on that entry
-  so that when it needs to cleanup the database it could sort them by the
-  timestamp and remove the oldest ones. Default quota is set to 50(percent).
+  be deleted when it hits the `state.row_limit`. Default quota is set to 50%.
+  When an entry in the database is used (e.g. during the `dvc status`), DVC
+  updates the timestamp on that entry. This way, when the database needs a
+  cleanup, DVC can sort entries chronologically, and remove the oldest ones.
 
 ## Example: Set the debug level
 

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

@@ -58,8 +58,9 @@ specified, the set of data files to fetch is determined by analyzing all
 DVC-files in the current branch, unless `--all-branches` or `--all-tags` is
 specified.
 
-The default remote is used unless `--remote` is specified. See `dvc remote add`
-for more information on how to configure different remote storage providers.
+The default remote is used (see `dvc config core.remote`) unless the `--remote`
+option is used. See `dvc remote add` for more information on how to configure
+different remote storage.
 
 `dvc fetch`, `dvc pull`, and `dvc push` are related in that these 3 commands
 perform data synchronization among local and remote storage. The specific way in
@@ -73,25 +74,24 @@ by `dvc fetch` (unless the `-a` or `-T` options are used).
 
 - `-r REMOTE`, `--remote REMOTE` - name of the
   [remote storage](/doc/command-reference/remote) to fetch from (see
-  `dvc remote list`). If not specified, the default remote is used (see
-  `dvc config core.remote`). The argument `REMOTE` is a remote name defined
-  using the `dvc remote` command.
+  `dvc remote list`). The argument `REMOTE` is a remote name defined using
+  `dvc remote`.
 
-- `-d`, `--with-deps` - one or more `targets` should be specified for this
-  option to have effect. Determines files to download by tracking dependencies
-  to the target DVC-files (stages). By traversing all stage dependencies, DVC
-  searches backward from the target stages in the corresponding pipelines. This
-  means DVC will not fetch files referenced in later stages than the `targets`.
+- `-d`, `--with-deps` - determines files to download by tracking dependencies to
+  the target DVC-files (stages). If no `targets` 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 fetch
+  files referenced in later stages than the `targets`.
 
 - `-R`, `--recursive` - determines the files to fetch by searching each target
-  directory and its subdirectories for DVC-files to inspect. `targets` is
-  expected to contain one or more directories for this option to have effect.
+  directory and its subdirectories for DVC-files to inspect. If there are no
+  directories among the `targets`, this option is ignored.
 
 - `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle
-  the downloading of files from the remote. Using more jobs may improve the
-  total download speed if a combination of small and large files are being
-  fetched. The default value is `4 * cpu_count()`. For SSH remotes default is
-  just 4.
+  the downloading of files from the remote. The default value is
+  `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs
+  may improve the total download speed if a combination of small and large files
+  are being fetched.
 
 - `-a`, `--all-branches` - fetch cache for all Git branches instead of just the
   current workspace. This means DVC may download files needed to reproduce

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

@@ -57,8 +57,8 @@ restored using `dvc fetch`, as long as they have previously been uploaded with
   if `-c` option is specified.
 
 - `-j`, `--jobs` - garbage collector parallelism level. The default value is
-  `4 * cpu_count()`. For SSH remotes default is 4. For now only some phases of
-  GC are parallel.
+  `4 * cpu_count()`. For SSH remotes, the default is just `4`. For now only some
+  phases of GC are parallel.
 
 - `-f`, `--force` - force garbage collection. Skip confirmation prompt.
 

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

@@ -52,19 +52,18 @@ name.
 ## Options
 
 - `-o`, `--out` - specify a path (directory and/or file name) to the desired
-  location to place the download file in. The default value (when this option
-  isn't used) is the current working directory (`.`) and original file name. If
-  an existing directory is specified, then the output will be placed inside of
-  it.
+  location to place the downloaded file in (instead of using the current working
+  directory). If an existing directory is specified, the output will be placed
+  inside of it.
 
 - `--rev` - commit hash, branch or tag name, etc. (any
   [Git revision](https://git-scm.com/docs/revisions)) of the repository to
   download the file or directory from. The latest commit in `master` (tip of the
   default branch) is used by default when this option is not specified.
 
 - `--show-url` - instead of downloading the file or directory, just print the
-  storage location (URL) of the target data. `path` is expected to represent a
-  cached, DVC-tracked file for this option to have effect.
+  storage location (URL) of the target data. If `path` is a Git-tracked file,
+  this option is ignored.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -154,7 +153,7 @@ again, like in the previous example. But this time, clone it first to see
 `dvc get` in action inside a <abbr>DVC project</abbr>.
 
 ```dvc
-$ git clone git@github.com:iterative/example-get-started.git
+$ git clone https://github.com/iterative/example-get-started
 $ cd example-get-started
 ```
 

public/static/docs/command-reference/import-url.md

@@ -108,12 +108,9 @@ up to date from the external data source.
 
 ## Options
 
-- `-f`, `--file` - specify name of the DVC-file it generates. By default the
-  DVC-file name generated is `<file>.dvc`, where `<file>` is file name of the
-  output (`out`). The stage file is placed in the same directory where
-  `dvc import-url` is run by default, but `-f` can be used to change this
-  location and file name, by including a path in the provided value (e.g.
-  `-f stages/stage.dvc`).
+- `-f`, `--file` - specify a path and/or file name for the DVC-file created by
+  this command (e.g. `-f stages/stage.dvc`). This overrides the default file
+  name: `<file>.dvc`, where `<file>` is the file name of the output (`out`).
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

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

@@ -69,10 +69,9 @@ data artifact from the source repo.
 ## Options
 
 - `-o`, `--out` - specify a path (directory and/or file name) to the desired
-  location to place the imported data and import stage (DVC-file) in. The
-  default value (when this option isn't used) is the current working directory
-  (`.`) and original file name. If an existing directory is specified, then the
-  output will be placed inside of it.
+  location to place the imported file in (instead of using the current working
+  directory). If an existing directory is specified, the output will be placed
+  inside of it.
 
 - `--rev` - commit hash, branch or tag name, etc. (any
   [Git revision](https://git-scm.com/docs/revisions)) of the repository to

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

@@ -35,13 +35,11 @@ They're calculated between two commits (hash, branch, tag, or any
 
 ## Options
 
-- `--targets` - specific metric files or directories to calculate metrics
-  differences for. If omitted (default), this command uses all metric files
-  found in both Git references.
+- `--targets` - limit the comparison to these specific metric files.
 
 - `-R`, `--recursive` - determines the metric files to use by searching each
-  target directory and its subdirectories for DVC-files to inspect. `targets` is
-  expected to contain one or more directories for this option to have effect.
+  target directory and its subdirectories for DVC-files to inspect. If there are
+  no directories among the `targets`, this option is ignored.
 
 - `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw`
   (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to determine

public/static/docs/command-reference/metrics/show.md

@@ -89,8 +89,8 @@ compares them with a previous version.
   `-aT` flag.
 
 - `-R`, `--recursive` - determines the metric files to show by searching each
-  target directory and its subdirectories for DVC-files to inspect. `targets` is
-  expected to contain one or more directories for this option to have effect.
+  target directory and its subdirectories for DVC-files to inspect. If there are
+  no directories among the `targets`, this option is ignored.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

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

@@ -59,10 +59,10 @@ reflinks or hardlinks to put it in the workspace without copying. See
 
 ## Options
 
-- `-r REMOTE`, `--remote REMOTE` specifies which remote to pull from (see
-  `dvc remote list`). The value for `REMOTE` is a name defined using
-  `dvc remote`. If the option is not specified, then the default remote
-  (configured with the `core.config` config option) is used.
+- `-r REMOTE`, `--remote REMOTE` - name of the
+  [remote storage](/doc/command-reference/remote) to pull from (see
+  `dvc remote list`). The argument `REMOTE` is a remote name defined using
+  `dvc remote`.
 
 - `-a`, `--all-branches` - determines the files to download by examining
   DVC-files in all Git branches instead of just those present in the current
@@ -73,26 +73,26 @@ reflinks or hardlinks to put it in the workspace without copying. See
   to save different experiments or project checkpoints. Note that both options
   can be combined, for example using the `-aT` flag.
 
-- `-d`, `--with-deps` - one or more `targets` should be specified for this
-  option to have effect. Determines files to download by tracking dependencies
-  to the target DVC-files (stages). By traversing all stage dependencies, DVC
-  searches backward from the target stages in the corresponding pipelines. This
-  means DVC will not pull files referenced in later stages than the `targets`.
+- `-d`, `--with-deps` - determines files to download by tracking dependencies to
+  the target DVC-files (stages). If no `targets` 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 pull
+  files referenced in later stages than the `targets`.
 
 - `-R`, `--recursive` - determines the files to pull by searching each target
-  directory and its subdirectories for DVC-files to inspect. `targets` is
-  expected to contain one or more directories for this option to have effect.
+  directory and its subdirectories for DVC-files to inspect. If there are no
+  directories among the `targets`, this option is ignored.
 
 - `-f`, `--force` - does not prompt when removing workspace files, which occurs
   when these file no longer match the current DVC-file references. This option
   surfaces behavior from the `dvc fetch` and `dvc checkout` commands because
   `dvc pull` in effect performs those 2 functions in a single command.
 
-- `-j JOBS`, `--jobs JOBS` - specifies number of jobs to run simultaneously
-  while downloading files from the remote. The effect is to control the number
-  of files downloaded simultaneously. Default is `4 * cpu_count()`. For example
-  with `-j 1` DVC downloads one file at a time, with `-j 2` it downloads two at
-  a time, and so forth. For SSH remotes default is set to 4.
+- `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle
+  the downloading of files from the remote. The default value is
+  `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs
+  may improve the total download speed if a combination of small and large files
+  are being fetched.
 
 - `-h`, `--help` - prints the usage/help message, and exit.