Merge pull request #1971 from iterative/cmd/remove

cmd: corrections and copy edits, etc. in remove

content/docs/command-reference/gc.md

@@ -51,9 +51,9 @@ The default remote is cleaned (see `dvc config core.remote`) unless the
 
 ## Options
 
-- `-w`, `--workspace` - keep files and directories _only_ referenced in the
-  current workspace This option is enabled automatically if `--all-tags`,
-  `--all-branches`, or `--all-commits` are used.
+- `-w`, `--workspace` - keep _only_ files and directories referenced in the
+  workspace. Note that this behavior is implied in `--all-tags`,
+  `--all-branches`, and `--all-commits`.
 
 - `-a`, `--all-branches` - keep cached objects referenced in all Git branches as
   well as in the workspace (implies `-w`). Useful if branches are used to track

content/docs/command-reference/remove.md

@@ -1,6 +1,7 @@
 # remove
 
-Remove stage, `.gitignore` entry, and unprotect outputs.
+Remove stages from `dvc.yaml` and/or stop tracking files or directories (and
+optionally delete them).
 
 ## Synopsis
 
@@ -13,35 +14,30 @@ positional arguments:
 
 ## Description
 
-This command safely removes stages from
-[dvc.yaml](/doc/user-guide/dvc-files-and-directories#dvcyaml-file), their
-`.gitignore` entries, and optionally removes from the <abbr>workspace</abbr>
-files or directories that are tracked by DVC. It takes one or more stage names
-(see `-n` option of `dvc run`) or `.dvc` files as target, removes it, and
-optionally removes all of its outputs (`outs` field).
+Safely removes `.dvc` files or stages from `dvc.yaml`. This includes deleting
+the corresponding `.gitignore` entries (based on the `outs` fields removed).
 
-If there are no stages left in
-[dvc.yaml](/doc/user-guide/dvc-files-and-directories#dvcyaml-file) after stage
-removal then both
-[dvc.yaml](/doc/user-guide/dvc-files-and-directories#dvcyaml-file) and
-[dvc.lock](/doc/user-guide/dvc-files-and-directories#dvclock-file) are removed
-from the workspace.
+> `dvc remove` doesn't remove files from the DVC <abbr>cache</abbr> or
+> [remote storage](/doc/command-reference/remote). Use `dvc gc` for that.
 
-Note that in the case when `targets` are `.dvc` files, the tracked files or
-directories (`outs` in the `.dvc` file) are _not_ removed by this command unless
-`--outs` is specified.
+It takes one or more stage names (see `-n` option of `dvc run`) or `.dvc` file
+names as `targets`.
 
-`dvc remove` does not remove files from the DVC cache or remote storage (see
-`dvc gc`). However, remember to run `dvc push` to save the files you actually
-want to use or share in the future.
+If there are no stages left in `dvc.yaml` after the removal, then both
+`dvc.yaml` and `dvc.lock` are deleted.
 
-Refer to [Updating Tracked Files](/doc/user-guide/how-to/update-tracked-files)
-to see how it can be used to replace or modify files that are tracked by DVC.
+Note that the actual <abbr>output</abbr> files or directories of the stage
+(`outs` field) are not removed by this command, unless the `--outs` option is
+used.
+
+💡 Refer to [Undo Adding Data](/doc/user-guide/how-to/undo-adding-data) to see
+how it helps replace data that is tracked by DVC.
 
 ## Options
 
-- `--outs` - remove the outputs of any stage `targets` as well. This is always
-  applied automatically for `.dvc` file targets.
+- `--outs` - remove the outputs of any `targets` as well.
+
+  ⚠️This option may be irreversible (e.g. if the data isn't cached).
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -50,24 +46,25 @@ to see how it can be used to replace or modify files that are tracked by DVC.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Example: remove a tracked file (or directory)
+## Example: remove a .dvc file
 
 Let's imagine we have `foo.csv` and `bar.csv` files, that are already
 [tracked](/doc/command-reference/add) by DVC:
 
 ```dvc
-$ ls *.csv*
+$ ls
 bar.csv  bar.csv.dvc  foo.csv  foo.csv.dvc
 $ cat .gitignore
 /foo.csv
 /bar.csv
 ```
 
-This removed the `foo.csv.dvc` file, and lists `.gitignore` to double check that
-the corresponding entry is gone from there:
+This removes `foo.csv.dvc` and double checks that its entry is gone from
+`.gitignore`:
 
 ```dvc
 $ dvc remove foo.csv.dvc
+
 $ ls
 bar.csv  bar.csv.dvc  foo.csv
 $ cat .gitignore
@@ -76,10 +73,10 @@ $ cat .gitignore
 
 > The same procedure applies to tracked directories.
 
-## Example: remove a stage
+## Example: remove a stage and its output
 
-Let's imagine we have a stage named `train` in our `dvc.yaml` file, and
-corresponding files in the <abbr>workspace</abbr>:
+Let's imagine we have a `train` stage in `dvc.yaml`, and corresponding files in
+the <abbr>workspace</abbr>:
 
 ```yaml
 train:
@@ -96,14 +93,14 @@ $ ls
 dvc.lock  dvc.yaml  foo.csv  foo.csv.dvc  model  train.py
 ```
 
-Running `dvc remove` on the stage name will remove that entry from `dvc.yaml`,
-and remove its outputs from `.gitignore`. With the `--outs` option, the outputs
-itself (just `model` in this example) are also removed:
+Using `dvc remove` on the stage name will remove that entry from `dvc.yaml`, and
+its outputs from `.gitignore`. With the `--outs` option, its outputs are also
+deleted (just the `model` file in this example):
 
 ```dvc
 $ dvc remove train --outs
 $ ls
 dvc.lock  dvc.yaml  foo.csv  foo.csv.dvc  train.py
 ```
 
-Notice that the dependencies (`data.csv` and `train.py`) are not removed.
+> Notice that the dependencies (`data.csv` and `train.py`) are not deleted.