diff --git a/content/docs/command-reference/run.md b/content/docs/command-reference/run.md index f2f49a3527..2f9ee6260f 100644 --- a/content/docs/command-reference/run.md +++ b/content/docs/command-reference/run.md @@ -34,8 +34,9 @@ kinds of stage [dependencies and outputs](#dependencies-and-outputs). The remaining terminal input provided to `dvc run` after `-`/`--` flags will become the required [`command` argument](#the-command-argument). -As suggested in its name, `dvc run` executes stage commands when used, unless -the `--no-exec` option is used. +As suggested in its name, `dvc run` +[executes stages](#stage-execution-and-reproduction) when used, unless the +`--no-exec` option is used. ### Dependencies and outputs @@ -132,6 +133,22 @@ time functions, hardware dependencies, etc.) +### Stage execution and reproduction + +`dvc run` executes the given `command` so the defined outputs are written, +unless the same `dvc run` has already happened in this workspace. +Put in other words, if an identical stage already exists in +[`dvc.yaml`](/doc/user-guide/dvc-files-and-directories#dvcyaml-files), and its +outputs correspond to the cached files (hash values are compared), +then `dvc run` does not execute the `command`. + +`dvc repro` provides an interface to check the status (see also `dvc status`), +and reproduce stages and pipelines created with `dvc run` by executing (again) +the necessary stages. + +> Note that stages without dependencies are considered always changed, so +> `dvc repro` always executes them. + ## Options - `-n `, `--name ` (required) - specify a name for the stage