docs: doc repro --glob and update targets arg info.

content/docs/command-reference/repro.md

@@ -10,21 +10,26 @@ analyzing dependencies and <abbr>outputs</abbr> of the target stages.
 ```usage
 usage: dvc repro [-h] [-q | -v] [-f] [-s] [-m] [--dry] [-i]
                  [-p] [-P] [-R] [--no-run-cache] [--force-downstream]
-                 [--no-commit] [--downstream] [--pull]
-                 [targets [targets ...]]
+                 [--no-commit] [--downstream] [--pull] [--glob]
+                 [targets [<target> ...]]
 
 positional arguments:
-  targets        Stage or path to dvc.yaml or .dvc file to reproduce. Using -R,
-                 directories to search for stages can also be given.
+  targets       Limit command scope to these .dvc or dvc.yaml files,
+                or stage names.
 ```
 
+> See [`targets`](#options) for more details.
+
 ## Description
 
 `dvc repro` provides a way to regenerate data pipeline results, by restoring the
 dependency graph (a [DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph))
 implicitly defined by the stages listed in `dvc.yaml`. The commands defined in
-these stages can then be executed in the correct order, reproducing pipeline
-results.
+these stages are then be executed in the correct order.
+
+For stages with multiple commands (having a list in the `cmd` field), commands
+are run one after the other in the order they are defined. The failure of any
+command will halt the remaining stage execution, and raises an error.
 
 > Pipeline stages are defined in a `dvc.yaml` file (either manually or by using
 > `dvc run`) while initial data dependencies can be registered with `dvc add`.
@@ -37,30 +42,21 @@ and <abbr>caches</abbr> the pipeline's <abbr>outputs</abbr> along the way.
 💡 For convenience, a Git hook is available to remind you to `dvc repro` when
 needed after a `git commit`. See `dvc install` for more details.
 
+[Stage](/doc/command-reference/run) outputs are deleted from the
+<abbr>workspace</abbr> before executing the stage commands that produce them.
 `dvc repro` does not run `dvc fetch`, `dvc pull` or `dvc checkout` to get data
 files, intermediate or final results (except if the `--pull` option is used).
 
-By default, this command checks all [pipeline](/doc/command-reference/dag)
-stages to determine which ones have changed. Then it executes the corresponding
-commands (`cmd` field of `dvc.yaml`). [Stage](/doc/command-reference/run)
-outputs are deleted from the <abbr>workspace</abbr> before executing the stage
-commands that produce them.
-
-For stages with multiple commands (having a list in the `cmd` field), commands
-are run one after the other in the order they are defined. The failure of any
-command will halt the remaining stage execution, and raises an error.
-
 There are a few ways to restrict what will be regenerated by this command: by
-specifying stages as `targets`, or by using `--single-item`, among other
-options.
+specifying specific reproduction [`targets`](#options), or by using certain
+command [options](#options), such as `--single-item`.
 
 > Note that stages without dependencies are considered _always changed_, so
 > `dvc repro` always executes them.
 
-It stores all the data files, intermediate or final results in the
+`dvc repro` saves all the data files, intermediate or final results into the
 <abbr>cache</abbr> (unless the `--no-commit` option is used), and updates the
-hash values of changed dependencies and outputs in the `dvc.lock` and `.dvc`
-files.
+hash values of changed outputs in the `dvc.lock` and `.dvc` files.
 
 ### Parallel stage execution
 
@@ -97,6 +93,31 @@ up-to-date and only execute the final stage.
 
 ## Options
 
+- `targets` (optional argument) - one or more file or directory paths (to `.dvc`
+  or `dvc.yaml` files), or stage name(s) (`./dvc.yaml` by default). DVC will
+  reproduce them as detailed below.
+
+  - For **`dvc.yaml` files**, their [pipeline(s)](/doc/command-reference/dag)
+    are checked for changes, and reproduced as needed (explained in the command
+    [description](#description) above). E.g. `dvc repro pipes/linear/dvc.yaml`
+
+  - **Stage names** must be defined in `./dvc.yaml`. E.g.
+    `dvc repro train-vision`. Stages in other `dvc.yaml` files can be given
+    using by using a colon `:` following the path to that file. E.g.
+    `models/dvc.yaml:prepare`
+
+  - Files and directories tracked by **`.dvc` files** given as `targets` are
+    updated (same as `dvc add`). E.g. `dvc repro data.dvc`
+
+    > Note that [frozen](/doc/command-reference/freeze) `.dvc` files are
+    > ignored.
+
+- `--glob` - causes the `targets` to be interpreted as wildcard
+  [patterns](https://docs.python.org/3/library/glob.html) to match for stages.
+  For example: `train-*` (certain stage names) or `models/dvc.yaml:train-*`
+  (stages in specific `dvc.yaml` file). Note that it does not match patterns
+  with the path, only to the stages present in the specified file.
+
 - `-f`, `--force` - reproduce a pipeline, regenerating its results, even if no
   changes were found. This executes all of the stages by default, but it can be
   limited with the `targets` argument, or the `-s`, `-p` options.
@@ -105,15 +126,21 @@ up-to-date and only execute the final stage.
   recursive search for changed dependencies. Multiple stages are executed
   (non-recursively) if multiple stage names are given as `targets`.
 
-- `-R`, `--recursive` - determines the stages to reproduce by searching each
-  target directory and its subdirectories for stages (in `dvc.yaml`) to inspect.
-  If there are no directories among the targets, this option is ignored.
+- `-R`, `--recursive` - looks for `dvc.yaml` files to reproduce in any
+  directories given as `targets`, and in their subdirectories. If there are no
+  directories among the targets, this option has no effect.
 
 - `--no-commit` - do not store the outputs of this execution in the cache
   (`dvc.yaml` and `dvc.lock` are still created or updated); useful to avoid
   caching unnecessary data when exploring different data or stages. Use
   `dvc commit` to finish the operation.
 
+- `-p`, `--pipeline` - reproduce the entire pipelines that the `targets` belong
+  to. Use `dvc dag` to show the parent pipeline of a target.
+
+- `-P`, `--all-pipelines` - reproduce all pipelines for all `dvc.yaml` files
+  present in the DVC project.
+
 - `-m`, `--metrics` - show metrics after reproduction. The target pipelines must
   have at least one metrics file defined either with the `dvc metrics` command,
   or by the `-M` or `-m` options of the `dvc run` command.
@@ -124,12 +151,6 @@ up-to-date and only execute the final stage.
 - `-i`, `--interactive` - ask for confirmation before reproducing each stage.
   The stage is only executed if the user types "y".
 
-- `-p`, `--pipeline` - reproduce the entire pipelines that the `targets` belong
-  to. Use `dvc dag <target>` to show the parent pipeline of a target.
-
-- `-P`, `--all-pipelines` - reproduce all pipelines for all `dvc.yaml` files
-  present in the DVC project.
-
 - `--no-run-cache` - execute stage commands even if they have already been run
   with the same dependencies/outputs/etc. before.