From 44a16149f64e8e8d336a7b147937b3d9ead5e148 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 11 Aug 2021 11:14:26 -0500 Subject: [PATCH 01/13] guide: summarize Sharing Exps intro --- .../sharing-experiments.md | 34 +++++++------------ 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index cd6103b019..4de2f181ff 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -1,37 +1,27 @@ # Sharing Experiments -There are two types of remotes that can store experiments. Git remotes are -distributed copies of the Git repository, for example on GitHub or GitLab. - -[DVC remotes](/doc/command-reference/remote) on the other hand are -storage-specific locations (e.g. Amazon S3 or Google Drive) which we can -configure with `dvc remote`. DVC uses them to store and fetch large files that -don't normally fit inside Git repos. - -DVC needs both kinds of remotes for backing up and sharing experiments. - -Experiment files that are normally tracked in Git (like code versions) are -shared using Git remotes, and files or directories tracked with DVC (like -datasets) are shared using DVC remotes. - -> See [Git remotes guide] and `dvc remote add` for information on setting them -> up. +Two types of _remotes_ are needed to upload experiments for sharing. +[Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) +are distributed copies of the Git repository, hosted for example on GitHub or +GitLab. Small files like experimental code and +[DVC metafiles](/doc/user-guide/project-structure) files will go there. +[DVC remotes](/doc/command-reference/remote) on the other hand are data storage +locations (e.g. Amazon S3 or Google Drive). You can use them to back up and +[share data](/doc/use-cases/sharing-data-and-model-files) files and directories +that don't fit inside Git repos. + +> See this [Git remotes guide] and `dvc remote add` for ifo. on setting them up. [git remotes guide]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes -Normally, there should already be a Git remote called `origin` when you clone a -repo. Use `git remote -v` to list your Git remotes: +You can list your remotes with `git remote -v` and `dvc remote list`: ```dvc $ git remote -v origin https://github.com/iterative/get-started-experiments (fetch) origin https://github.com/iterative/get-started-experiments (push) -``` - -Similarly, you can see the DVC remotes in you project using `dvc remote list`: -```dvc $ dvc remote list storage https://remote.dvc.org/get-started-experiments ``` From 3dbcb5b24a6e9f989c1f8ca2143abd09a0eb37f4 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Aug 2021 13:18:31 -0500 Subject: [PATCH 02/13] ref: link from exp push/pull to Exp Sharing guide --- content/docs/command-reference/exp/pull.md | 6 ++++-- content/docs/command-reference/exp/push.md | 7 +++++-- content/docs/command-reference/exp/run.md | 2 +- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/content/docs/command-reference/exp/pull.md b/content/docs/command-reference/exp/pull.md index 32fee2b766..449e52769f 100644 --- a/content/docs/command-reference/exp/pull.md +++ b/content/docs/command-reference/exp/pull.md @@ -17,8 +17,10 @@ positional arguments: ## Description -The `dvc exp push` and `dvc exp pull` commands are the means for sharing -experiments across repository copies via Git (and DVC) remotes. +The `dvc exp push` and `dvc exp pull` commands are the means for +[sharing experiments] across repository copies via Git and DVC remotes. + +[sharing experiments]: /doc/user-guide/experiment-management/sharing-experiments > Plain `git push` and `git fetch` don't work with `dvc experiments` because > these are saved under custom Git references. See **How does DVC track diff --git a/content/docs/command-reference/exp/push.md b/content/docs/command-reference/exp/push.md index eaa4a793d2..2638c67479 100644 --- a/content/docs/command-reference/exp/push.md +++ b/content/docs/command-reference/exp/push.md @@ -17,8 +17,11 @@ positional arguments: ## Description -The `dvc exp push` and `dvc exp pull` commands are the means for sharing -experiments across repository copies via Git (and DVC) remotes. +The `dvc exp push` and `dvc exp pull` commands are the means for +[sharing experiments] across repository copies via Git and DVC +remotes. + +[sharing experiments]: /doc/user-guide/experiment-management/sharing-experiments > Plain `git push` and `git fetch` don't work with `dvc experiments` because > these are saved under custom Git references. See **How does DVC track diff --git a/content/docs/command-reference/exp/run.md b/content/docs/command-reference/exp/run.md index 295e647928..885d230083 100644 --- a/content/docs/command-reference/exp/run.md +++ b/content/docs/command-reference/exp/run.md @@ -44,7 +44,7 @@ option. 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 the Git remote by default +out by DVC). Note that these commits are not pushed to Git remotes by default (see `dvc exp push`). From 3fff05146812e3466b335b50eec34d6ea8969a8c Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Aug 2021 13:22:34 -0500 Subject: [PATCH 03/13] Update content/docs/user-guide/experiment-management/sharing-experiments.md --- .../user-guide/experiment-management/sharing-experiments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 4de2f181ff..bfe616b238 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -10,7 +10,7 @@ locations (e.g. Amazon S3 or Google Drive). You can use them to back up and [share data](/doc/use-cases/sharing-data-and-model-files) files and directories that don't fit inside Git repos. -> See this [Git remotes guide] and `dvc remote add` for ifo. on setting them up. +> See this [Git remotes guide] and `dvc remote add` for info. on setting them up. [git remotes guide]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes From c419fe6ca82eda1f39e61fed87a79c1cf5c38377 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Aug 2021 13:40:39 -0500 Subject: [PATCH 04/13] guide: rename Exp Sharing sections --- .../experiment-management/sharing-experiments.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 4de2f181ff..2e495e93ef 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -26,7 +26,7 @@ $ dvc remote list storage https://remote.dvc.org/get-started-experiments ``` -## Uploading experiments to remotes +## Uploading experiments You can upload an experiment and its files to both remotes using `dvc exp push` (requires the Git remote name and experiment name as arguments). @@ -53,7 +53,7 @@ performance also depend on the connection bandwidth and remote configurations. [run-cache]: /doc/user-guide/project-structure/internal-files#run-cache -## Listing experiments remotely +## Listing remote experiments In order to list experiments in a DVC project, you can use the `dvc exp list` command. With no command line options, it lists the experiments in the current @@ -98,7 +98,7 @@ cnn-64 cnn-96 ``` -## Downloading experiments from remotes +## Downloading experiments When you clone a DVC repository, it doesn't fetch any experiments by default. In order to get them, use `dvc exp pull` (with the Git remote and the experiment @@ -120,7 +120,7 @@ can set the number with `--jobs` (`-j`). If an experiment being pulled already exists in the local project, DVC won't overwrite it unless you supply `--force`. -### Example: Pushing or pulling multiple experiments +## Example: Sharing multiple experiments You can create a loop to upload or download all experiments like this: @@ -130,8 +130,7 @@ $ dvc exp list --all --names-only | while read -r expname ; do \ done ``` -> Without `--all`, only the experiments derived from the current commit will be -> pushed/pulled. +## Example: Dedicated experiment directories ## Example: Creating a directory for an experiment From c473e515c451bd2e51bfd426796b4f04de688c86 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Aug 2021 13:41:11 -0500 Subject: [PATCH 05/13] guide: summarize Exp Sharing examples --- .../sharing-experiments.md | 38 ++++++++----------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 2e495e93ef..0e0de3dd97 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -122,7 +122,8 @@ overwrite it unless you supply `--force`. ## Example: Sharing multiple experiments -You can create a loop to upload or download all experiments like this: +You can create a loop to push or pull all experiments. For example on Linux +terminal: ```dvc $ dvc exp list --all --names-only | while read -r expname ; do \ @@ -132,18 +133,15 @@ done ## Example: Dedicated experiment directories -## Example: Creating a directory for an experiment - -A good way to isolate experiments is to create a separate home directory for -each one. +A good way to isolate experiments is to create a separate directory outside the +current repository for each one. > Another alternative is to use `dvc exp apply` and `dvc exp branch`, but here > we'll see how to use `dvc exp pull` to copy an experiment. -Suppose there is a DVC repository in `~/my-project` with multiple -experiments. Let's create a copy of experiment `exp-abc12` from there. - -First, clone the repo into another directory: +Suppose there is a DVC repo in `~/my-project` with multiple experiments. Let's +create a copy of experiment `exp-abc12` from it. First, clone the repo into +another directory: ```dvc $ git clone ~/my-project ~/my-experiment @@ -160,29 +158,25 @@ main: ... ``` -If there is no DVC remote in the original repository, you can define its -cache as the clone's `dvc remote`: +If the original repository doesn't have a `dvc remote`, you can define its +cache as the clone's remote storage: ```dvc $ dvc remote add --local --default storage ~/my-project/.dvc/cache ``` -> ⚠️ `--local` is important here, so that the configuration change doesn't get -> to the original repo accidentally. +> ⚠️ `--local` is important here, so that the configuration changes don't +> accidentally get to the original repo. -If there's a DVC remote for the project, assuming the experiments have been -pushed there, you can pull the one in question: +Having a DVC remote (and assuming the experiments have been pushed or cached +there) you can `dvc exp pull` the one in question; You can then can +`dvc exp apply` it and get a workspace that contains all of its +files: ```dvc $ dvc exp pull origin exp-abc12 -``` - -Then we can `dvc apply` this experiment and get a workspace that -contains all of its files: - -```dvc $ dvc exp apply exp-abc12 ``` -Now you have a dedicated directory for your experiment, containing all its +Now you have a separate repo directory for your experiment, containing all its artifacts! From 1da6bd4135c4afa44f6a5adc403241f3758171af Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 15 Aug 2021 13:47:45 -0500 Subject: [PATCH 06/13] guide: link from Exp Mgmt index to Sharing --- content/docs/user-guide/experiment-management/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/docs/user-guide/experiment-management/index.md b/content/docs/user-guide/experiment-management/index.md index f7d49feafb..dfcf9d18ba 100644 --- a/content/docs/user-guide/experiment-management/index.md +++ b/content/docs/user-guide/experiment-management/index.md @@ -47,12 +47,14 @@ The `dvc experiments` features are designed to support these main approaches: them in batches. 1. Make experiments [persistent] by committing them to your repository history. +1. Easily [share and isolate] experiments using Git and DVC remotes. [experiments]: /doc/user-guide/experiment-management/dvc-experiments [queue]: /doc/command-reference/exp/run#queueing-and-parallel-execution [checkpoints]: /doc/user-guide/experiment-management/checkpoints [persistent]: /doc/user-guide/experiment-management/dvc-experiments#persistent-experiments + [share and isolate]: /doc/user-guide/experiment-management/sharing-experiments > 👨‍💻 See [Get Started: Experiments](/doc/start/experiments) for a hands-on > introduction to DVC experiments. From ad193b9df346e8343d19028d131c22a4b1a221f7 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:17:59 -0500 Subject: [PATCH 07/13] guide: ~~isolate~~ from link to Exp Sharing per https://github.com/iterative/dvc.org/pull/2711#pullrequestreview-730211648 --- content/docs/user-guide/experiment-management/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/index.md b/content/docs/user-guide/experiment-management/index.md index dfcf9d18ba..8ad9841637 100644 --- a/content/docs/user-guide/experiment-management/index.md +++ b/content/docs/user-guide/experiment-management/index.md @@ -47,7 +47,7 @@ The `dvc experiments` features are designed to support these main approaches: them in batches. 1. Make experiments [persistent] by committing them to your repository history. -1. Easily [share and isolate] experiments using Git and DVC remotes. +1. Easily [share experiments] using Git and DVC remotes. [experiments]: /doc/user-guide/experiment-management/dvc-experiments [queue]: /doc/command-reference/exp/run#queueing-and-parallel-execution From 7463e85c18d714de9eea78431f001f739b345078 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:19:07 -0500 Subject: [PATCH 08/13] Update content/docs/user-guide/experiment-management/sharing-experiments.md Co-authored-by: David de la Iglesia Castro --- .../user-guide/experiment-management/sharing-experiments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index bfe616b238..9ffcec4895 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -19,8 +19,8 @@ You can list your remotes with `git remote -v` and `dvc remote list`: ```dvc $ git remote -v -origin https://github.com/iterative/get-started-experiments (fetch) -origin https://github.com/iterative/get-started-experiments (push) +origin git@github.com:iterative/get-started-experiments.git (fetch) +origin git@github.com:iterative/get-started-experiments.git (push) $ dvc remote list storage https://remote.dvc.org/get-started-experiments From 2744a97ddf7720d021656460c4bdf2173d8b1cbe Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:26:32 -0500 Subject: [PATCH 09/13] guide: mention only SSH Git URLs support exp sharing per https://github.com/iterative/dvc.org/pull/2711#pullrequestreview-732522579 --- .../experiment-management/sharing-experiments.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 9ffcec4895..d55ffe0798 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -10,7 +10,12 @@ locations (e.g. Amazon S3 or Google Drive). You can use them to back up and [share data](/doc/use-cases/sharing-data-and-model-files) files and directories that don't fit inside Git repos. -> See this [Git remotes guide] and `dvc remote add` for info. on setting them up. +> See this [Git remotes guide] and `dvc remote add` for info. on setting them +> up. +> ⚠️ Note that only [SSH Git URLs] support DVC experiment sharing. + +[ssh git urls]: + https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_protocols [git remotes guide]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes From 2e3379968939486bb00ae54e2bab4777b4f8f363 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:34:01 -0500 Subject: [PATCH 10/13] guide: update dvc remote example in sharing exps --- .../user-guide/experiment-management/sharing-experiments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index d55ffe0798..5c8885a1b3 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -28,7 +28,7 @@ origin git@github.com:iterative/get-started-experiments.git (fetch) origin git@github.com:iterative/get-started-experiments.git (push) $ dvc remote list -storage https://remote.dvc.org/get-started-experiments +storage s3://mybucket/my-dvc-store ``` ## Uploading experiments to remotes From c60b5fe3bca0aab8901f48845bffd758b9f1b3d4 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:42:30 -0500 Subject: [PATCH 11/13] yarn format some files per https://app.circleci.com/pipelines/github/iterative/dvc.org/10086/workflows/9b1bf89f-a432-49f2-9a20-72fe77dd4102/jobs/10145 --- content/docs/command-reference/exp/pull.md | 4 ++-- content/docs/command-reference/exp/push.md | 5 ++--- content/docs/user-guide/experiment-management/index.md | 2 +- .../user-guide/experiment-management/sharing-experiments.md | 1 - 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/content/docs/command-reference/exp/pull.md b/content/docs/command-reference/exp/pull.md index 449e52769f..f9d3e5aeab 100644 --- a/content/docs/command-reference/exp/pull.md +++ b/content/docs/command-reference/exp/pull.md @@ -17,8 +17,8 @@ positional arguments: ## Description -The `dvc exp push` and `dvc exp pull` commands are the means for -[sharing experiments] across repository copies via Git and DVC remotes. +The `dvc exp push` and `dvc exp pull` commands are the means for [sharing +experiments] across repository copies via Git and DVC remotes. [sharing experiments]: /doc/user-guide/experiment-management/sharing-experiments diff --git a/content/docs/command-reference/exp/push.md b/content/docs/command-reference/exp/push.md index 2638c67479..46bcdcb2ea 100644 --- a/content/docs/command-reference/exp/push.md +++ b/content/docs/command-reference/exp/push.md @@ -17,9 +17,8 @@ positional arguments: ## Description -The `dvc exp push` and `dvc exp pull` commands are the means for -[sharing experiments] across repository copies via Git and DVC -remotes. +The `dvc exp push` and `dvc exp pull` commands are the means for [sharing +experiments] across repository copies via Git and DVC remotes. [sharing experiments]: /doc/user-guide/experiment-management/sharing-experiments diff --git a/content/docs/user-guide/experiment-management/index.md b/content/docs/user-guide/experiment-management/index.md index 8ad9841637..4a6fe96d80 100644 --- a/content/docs/user-guide/experiment-management/index.md +++ b/content/docs/user-guide/experiment-management/index.md @@ -54,7 +54,7 @@ The `dvc experiments` features are designed to support these main approaches: [checkpoints]: /doc/user-guide/experiment-management/checkpoints [persistent]: /doc/user-guide/experiment-management/dvc-experiments#persistent-experiments - [share and isolate]: /doc/user-guide/experiment-management/sharing-experiments +[share and isolate]: /doc/user-guide/experiment-management/sharing-experiments > 👨‍💻 See [Get Started: Experiments](/doc/start/experiments) for a hands-on > introduction to DVC experiments. diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 5c8885a1b3..286ac4ad57 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -16,7 +16,6 @@ that don't fit inside Git repos. [ssh git urls]: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_protocols - [git remotes guide]: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes From 8b6a3f6f7ecfbf8d90a670612b23d2eb3a89620a Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 06:33:20 -0500 Subject: [PATCH 12/13] prettier sharing-experiments.md --- .../user-guide/experiment-management/sharing-experiments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 1d981b18ae..90e791ef61 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -138,7 +138,7 @@ done ## Example: Dedicated experiment directories A good way to isolate experiments is to create a separate directory outside the -current repository for each one. +current repository for each one. > Another alternative is to use `dvc exp apply` and `dvc exp branch`, but here > we'll see how to use `dvc exp pull` to copy an experiment. From 209e848e892b17ba81b27249bfc99e5502b21f92 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 20 Aug 2021 16:15:04 -0500 Subject: [PATCH 13/13] Update content/docs/user-guide/experiment-management/sharing-experiments.md Co-authored-by: Casper da Costa-Luis --- .../user-guide/experiment-management/sharing-experiments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index 90e791ef61..d227bc0ef2 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -126,7 +126,7 @@ overwrite it unless you supply `--force`. ## Example: Sharing multiple experiments -You can create a loop to push or pull all experiments. For example on Linux +You can create a loop to push or pull all experiments. For example in a Linux terminal: ```dvc