remove: output file/dir by path

content/docs/command-reference/remove.md

@@ -9,27 +9,30 @@ optionally delete them).
 usage: dvc remove [-h] [-q | -v] [--outs] targets [targets ...]
 
 positional arguments:
-  targets        stages (found in dvc.yaml) or .dvc files to remove.
+  targets        Tracked files/directories, stage names (found in
+                 dvc.yaml), or .dvc files to remove.
 ```
 
 ## Description
 
-Safely removes `.dvc` files or stages from `dvc.yaml`. This includes deleting
-the corresponding `.gitignore` entries (based on the `outs` fields removed).
+Safely removes tracked data (by file name, stage name, or `.dvc` file path).
+This includes deleting the corresponding `.gitignore` entries.
 
 > `dvc remove` doesn't remove files from the DVC <abbr>cache</abbr> or
 > [remote storage](/doc/command-reference/remote). Use `dvc gc` for that.
 
-It takes one or more stage names (see `-n` option of `dvc run`) or `.dvc` file
-names as `targets`.
+It takes one or more stage names (see `-n` option of `dvc run`), `.dvc` file
+names or tracked files/directories as `targets`.
 
 If there are no stages left in `dvc.yaml` after the removal, then both
 `dvc.yaml` and `dvc.lock` are deleted. `.gitignore` is also deleted if there are
 no more entries left in it.
 
-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.
+Note that, when using stage name as target, 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 which will remove **all** of them.
+Alternatively, you can the names of individual <abbr>output</abbr> files or
+directories of a stage as `targets`.
 
 💡 Refer to [Undo Adding Data](/doc/user-guide/how-to/stop-tracking-data) to see
 how it helps replace data that is tracked by DVC.
@@ -47,61 +50,127 @@ how it helps replace data that is tracked by DVC.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Example: remove a .dvc file
+## Example: Remove stage outputs
 
-Let's imagine we have `foo.csv` and `bar.csv` files, that are already
-[tracked](/doc/command-reference/add) by DVC:
+Let's imagine we have a `train` stage in `dvc.yaml`, and corresponding files in
+the <abbr>workspace</abbr>:
+
+```yaml
+train:
+  cmd: python train.py data.csv
+  deps:
+    - data.csv
+    - train.py
+  outs:
+    - logs
+    - model.h5
+```
 
 ```dvc
 $ ls
-bar.csv  bar.csv.dvc  foo.csv  foo.csv.dvc
+dvc.lock  dvc.yaml  data.csv  data.csv.dvc  model.h5  logs  train.py
+
 $ cat .gitignore
-/foo.csv
-/bar.csv
+/data.csv
+/model.h5
+/logs
 ```
 
-This removes `foo.csv.dvc` and double checks that its entry is gone from
-`.gitignore`:
+Using `dvc remove` on the stage name will remove the stage from `dvc.yaml`, and
+corresponding entries from `.gitignore`. With the `--outs` option, the actual
+files and directories are deleted too (`logs/` and `model.h5` in this example):
 
 ```dvc
-$ dvc remove foo.csv.dvc
+$ dvc remove train --outs
 
 $ ls
-bar.csv  bar.csv.dvc  foo.csv
+dvc.lock  dvc.yaml  data.csv  data.csv.dvc  train.py
+
 $ cat .gitignore
-/bar.csv
+/data.csv
 ```
 
-> The same procedure applies to tracked directories.
+> Notice that the dependencies (`data.csv` and `train.py`) are not deleted.
 
-## Example: remove a stage and its output
+## Example: remove a specific stage output
 
-Let's imagine we have a `train` stage in `dvc.yaml`, and corresponding files in
-the <abbr>workspace</abbr>:
+Assuming we have the same initial <abbr>workspace</abbr> as before:
 
 ```yaml
 train:
-  cmd: python train.py data.py
+  cmd: python train.py data.csv
   deps:
     - data.csv
     - train.py
   outs:
-    - model
+    - logs
+    - model.h5
 ```
 
 ```dvc
 $ ls
-dvc.lock  dvc.yaml  foo.csv  foo.csv.dvc  model  train.py
+dvc.lock  dvc.yaml  data.csv  data.csv.dvc  model.h5  logs  train.py
+
+$ cat .gitignore
+/data.csv
+/model.h5
+/logs
 ```
 
-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 remove` can also be used on **individual** <abbr>outputs</abbr> of a
+stage (by file name):
 
 ```dvc
-$ dvc remove train --outs
+$ dvc remove model.h5
+
 $ ls
-dvc.lock  dvc.yaml  foo.csv  foo.csv.dvc  train.py
+dvc.lock  dvc.yaml  data.csv  data.csv.dvc  logs  train.py
+
+$ cat .gitignore
+/data.csv
+/logs
 ```
 
-> Notice that the dependencies (`data.csv` and `train.py`) are not deleted.
+`model.h5` file is removed from the <abbr>workspace</abbr> and `.gitignore`,
+but note that `dvc.yaml` is not updated.
+
+## Example: remove specific data
+
+Assuming we have the same initial <abbr>workspace</abbr> as before:
+
+```yaml
+train:
+  cmd: python train.py data.csv
+  deps:
+    - data.csv
+    - train.py
+  outs:
+    - logs
+    - model.h5
+```
+
+```dvc
+$ ls
+dvc.lock  dvc.yaml  data.csv  data.csv.dvc  model.h5  logs  train.py
+
+$ cat .gitignore
+/data.csv
+/model.h5
+/logs
+```
+
+Using `dvc remove` on a tracked file name will remove the corresponding `.dvc`
+file and `gitignore` entry:
+
+```dvc
+$ dvc remove data.csv
+
+$ ls
+dvc.lock  dvc.yaml  data.csv  model.h5  logs  train.py
+
+$ cat .gitignore
+/model.h5
+/logs
+```
+
+> The same procedure applies to tracked directories.

content/docs/user-guide/how-to/stop-tracking-data.md

@@ -30,7 +30,7 @@ corresponding `.gitignore` entry). The data file is now no longer being tracked
 after this:
 
 ```dvc
-$ dvc remove data.csv.dvc
+$ dvc remove data.csv
 
 $ git status
     Untracked files: