diff --git a/content/docs/command-reference/exp/run.md b/content/docs/command-reference/exp/run.md index b059732bec..de4aad52cb 100644 --- a/content/docs/command-reference/exp/run.md +++ b/content/docs/command-reference/exp/run.md @@ -32,36 +32,25 @@ data and code updates, or hyperparameter tuning. For the latter, you can use the `--set-param` (`-S`) option of this command to change `dvc param` values on-the fly. -Each experiment creates and tracks a project variation based on your -workspace changes. Experiments will have an auto-generated name -like `exp-bfe64` by default, which can be customized using the `--name` (`-n`) -option. +📖 See [DVC Experiments Overview][exp-overview] for more information. -
- -### ⚙️ How does DVC track experiments? - -Experiments are custom -[Git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References) -(found in `.git/refs/exps`) with a single commit based on `HEAD` (not checked -out by DVC). Note that these commits are not pushed to Git remotes by default -(see `dvc exp push`). - -
- -The results of the last `dvc exp run` can be seen in the workspace. To display -and compare multiple experiments, use `dvc exp show` or `dvc exp diff` -(`plots diff` also accepts experiment names as `revisions`). Use `dvc exp apply` -to restore the results of any other experiment instead. +Each experiment creates and tracks a project variation based on the changes in +your workspace. The results of the last `dvc exp run` will be +reflected in the workspace. Experiments will have an auto-generated ID like +`exp-bfe64` by default. A custom name can be given instead, using the `--name` +(`-n`) option -Successful experiments can be made [persistent] by committing them to the Git -repo. Unnecessary ones can be removed with `dvc exp remove`or `dvc exp gc` (or -abandoned). +To display and compare multiple experiments, use `dvc exp show` or +`dvc exp diff` (`plots diff` also accepts experiment names as `revisions`). Use +`dvc exp apply` to restore the results of any experiment, for example to [commit +them][persisting] to Git. Unnecessary experiments can be removed with +`dvc exp remove`or `dvc exp gc` (or abandoned). -> Note that experiment data will remain in the cache until you use -> regular `dvc gc` to clean it up. +> Note that experiment data will remain in the local cache until +> you use regular `dvc gc` to clean it up. -[persistent]: /doc/user-guide/experiment-management/persisting-experiments +[exp-overview]: /doc/user-guide/experiment-management/experiments-overview +[persisting]: /doc/user-guide/experiment-management/persisting-experiments ## Checkpoints diff --git a/content/docs/user-guide/experiment-management/experiments-overview.md b/content/docs/user-guide/experiment-management/experiments-overview.md index ddd69ad690..0e8a448898 100644 --- a/content/docs/user-guide/experiment-management/experiments-overview.md +++ b/content/docs/user-guide/experiment-management/experiments-overview.md @@ -1,10 +1,29 @@ # DVC Experiments Overview -DVC Experiments are captures automatically by DVC when you [run them]. +DVC Experiments are captures automatically by DVC when you [run them]. Each +experiment creates and tracks a project variation based on the changes in your +workspace. Experiments preserve the latest commit in the current +branch (Git `HEAD`) as their parent or _baseline_. + +
+ +### ⚙️ How does DVC track experiments? + +Experiments are custom [Git references] (found in `.git/refs/exps`) with a +single commit based on `HEAD` (not checked out by DVC). Note that these commits +are not pushed to Git remotes by default (see `dvc exp push`). + +
+ +Experiments will have an auto-generated ID like `exp-bfe64` by default. A custom +name can be given instead (using the `--name`/`-n` option of `dvc exp run`). + +> ID or name can be used to reference experiments with `dvc exp` subcommands. [run them]: /doc/user-guide/experiment-management/running-experiments +[git references]: https://git-scm.com/book/en/v2/Git-Internals-Git-References -## Basic Workflow +## Basic workflow `dvc exp` commands let you automatically track a variation to a committed project version (baseline). You can create independent groups of experiments