diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json index 46aecf3f0f..3af0842e8f 100644 --- a/content/docs/sidebar.json +++ b/content/docs/sidebar.json @@ -164,8 +164,7 @@ "update-tracked-data", "add-deps-or-outs-to-a-stage", "merge-conflicts", - "share-a-dvc-cache", - "share-many-experiments" + "share-a-dvc-cache" ] }, "setup-google-drive-remote", diff --git a/content/docs/user-guide/experiment-management/cleaning-experiments.md b/content/docs/user-guide/experiment-management/cleaning-experiments.md index 5064ec7bee..82dcc19c0f 100644 --- a/content/docs/user-guide/experiment-management/cleaning-experiments.md +++ b/content/docs/user-guide/experiment-management/cleaning-experiments.md @@ -18,12 +18,27 @@ main: cnn-64 cnn-128 $ dvc exp remove cnn-32 cnn-64 +Removed experiments: cnn-32,cnn-64 +``` + +## Removing multiple experiments (based on parent commit) + +You may wish to remove multiple experiments at once. For example, if you are +finished experimenting on the current Git commit and want to discard all +experiments derived from it, use `dvc exp remove --rev` with `HEAD`. + +```dvc $ dvc exp list -main: - cnn-128 +refs/tags/baseline-experiment: + cnn-128 + cnn-32 + cnn-64 + cnn-96 +$ dvc exp remove --rev HEAD +Removed experiments: cnn-128,cnn-32,cnn-64,cnn-96 ``` -## Removing multiple experiments +## Cleaning up experiments After you've completed a set of experiments, it may be easier to decide which of these to keep rather than which of these to remove. You can use `dvc exp gc` to @@ -147,6 +162,7 @@ $ dvc exp show --all-tags ```dvc $ dvc exp gc --all-tags + $ dvc exp show --all-tags ``` @@ -171,8 +187,8 @@ workspace that are not committed to the history. ### Deleting Experiment-Related Objects in DVC Cache -Note that `dvc exp gc` and `dvc exp remove` doesn't delete any objects in the -DVC cache. In order to remove the cache objects, e.g. model files, +Note that `dvc exp gc` and `dvc exp remove` do not delete any objects in the DVC +cache. In order to remove the cache objects, e.g. model files, intermediate artifacts, etc. related with the experiments, you can use `dvc gc` command. @@ -183,32 +199,13 @@ well. ## Removing experiments from remotes -As you push the experiments with `dvc exp push`, remotes may be become cluttered -with experiment references. - -DVC doesn't provide a shortcut for cleaning up the experiments in remotes but -you can use Git plumbing commands to remove experiment references from remotes. - -First get the list of experiments with their hash values. - -```dvc -$ git ls-remote origin 'refs/exps/*' -98b237f8d8da0964c9fa60c6b27f1dd4a214dabf refs/exps/17/2b1b9c885f10a73c76bd457a04878bee0e6d6f/exp-7424d -794854926931e84ebc90e829dbc09b3085391659 refs/exps/19/0e697aa566482ebdb8bdb65401382e76b1bce5/exp-ec039 -``` - -Then we can use `git push -d` as any other Git reference: - -```dvc -$ git push -d origin refs/exps/17/2b1b9c885f10a73c76bd457a04878bee0e6d6f/exp-7424d -``` - -If you want to delete **all** experiments in a remote, you can use a loop: +As you push the experiments with `dvc exp push`, Git remotes may be become +cluttered with experiment references. To remove experiments from a Git remote, +use `dvc exp remove -g`. ```dvc -$ git ls-remote origin 'refs/exps/*' | cut -f 2 | while read exppath ; do - git push -d origin "${exppath}" -done +$ dvc exp remove -g origin exp-ab780 +Removed experiments: exp-bb09c ``` ## Removing queued experiments diff --git a/content/docs/user-guide/experiment-management/comparing-experiments.md b/content/docs/user-guide/experiment-management/comparing-experiments.md index 1f107ee34e..c92ac41513 100644 --- a/content/docs/user-guide/experiment-management/comparing-experiments.md +++ b/content/docs/user-guide/experiment-management/comparing-experiments.md @@ -17,10 +17,10 @@ refs/tags/baseline-experiment: ``` If you want to list all the experiments in the repo regardless of their parent -commit, use the `--all` flag. +commit, use the `--all-commits` (`-A`) flag. ```dvc -$ dvc exp list --all +$ dvc exp list -A refs/tags/baseline-experiment: cnn-64 cnn-128 @@ -42,8 +42,8 @@ refs/tags/baseline-experiment: ``` This command lists remote experiments based on that repo's `HEAD`. You can use -`--all` to list all experiments, or add any other supported option to the remote -`dvc exp list` command. +`--all-commits` (`-A`) to list all experiments, or add any other supported +option to the remote `dvc exp list` command. [shared]: /doc/user-guide/experiment-management/sharing-experiments @@ -51,12 +51,14 @@ This command lists remote experiments based on that repo's `HEAD`. You can use `dvc exp list` may be printing too much information when it comes to feed its output to other commands. You can get only the names of the experiments via the -`--name-only` flag. For example, to get all the experiment names from a remote -(`origin`): +`--name-only` flag. For example, to download the model files from all +experiments in a remote: ```dvc -$ for experiment in $(dvc exp list origin --name-only --all) ; do - dvc exp pull "${experiment}" +$ for name in $(dvc exp list origin --name-only -A); do + dvc get --rev ${name} \ + git@github.com:iterative/example-dvc-experiments.git \ + models/model.h5 -o exps/${name}.h5 done ``` @@ -108,7 +110,8 @@ $ dvc exp show ``` `dvc exp show` only tabulates experiments in the workspace and in `HEAD`. You -can use `--all` flag to show all the experiments in the project instead. +can use `--all-commits` (`-A`) flag to show all the experiments in the project +instead. Note that [queued experiments] will be marked with an asterisk `*`. diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 3aa2ad00ca..679179f9f2 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -73,11 +73,8 @@ $ dvc exp push origin exp-abc123 Once pushed, you can easily [list remote experiments] (with `dvc exp list`). -> See also [How to Share Many Experiments][share many]. - [list remote experiments]: /doc/user-guide/experiment-management/comparing-experiments#list-experiments-saved-remotely -[share many]: /doc/user-guide/how-to/share-many-experiments ## Downloading experiments @@ -94,3 +91,13 @@ both of these configured (see this [earlier section](#preparation)). If an experiment being pulled already exists in the local project, DVC won't overwrite it unless you supply `--force`. + +## Sharing many experiments + +Use the`--rev` option of `dvc exp push` and `dvc exp pull` to share many +experiments at once. For example, to upload all experiments based on the latest +commit of the current branch (Git `HEAD`), use `--rev HEAD`: + +``` +$ dvc exp push --rev HEAD origin +``` diff --git a/content/docs/user-guide/how-to/share-many-experiments.md b/content/docs/user-guide/how-to/share-many-experiments.md deleted file mode 100644 index 550c8260a7..0000000000 --- a/content/docs/user-guide/how-to/share-many-experiments.md +++ /dev/null @@ -1,19 +0,0 @@ -# How to Share Many Experiments - -`dvc exp push` and `dvc exp pull` allow us to [share experiments] between -repositories via existing DVC and Git remotes. These however work on individual -experiments. - -Here's a simple shell loop to push or pull all experiments (Linux): - -```dvc -$ dvc exp list --all --name-only | while read -r expname ; do \ - dvc exp pull origin ${expname} \ -done -``` - -> 📖 See [Listing Experiments] for more info on `dvc exp list`. - -[share experiments]: /doc/user-guide/experiment-management/sharing-experiments -[listing experiments]: - /doc/user-guide/experiment-management/comparing-experiments#list-experiments-in-the-project