From d1422b10a66b378d961f0c33627eddc19e464f54 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Wed, 18 Aug 2021 03:44:11 -0500 Subject: [PATCH] guide: consolidate Exp Sharing intro (#2711) * guide: summarize Sharing Exps intro * ref: link from exp push/pull to Exp Sharing guide * Update content/docs/user-guide/experiment-management/sharing-experiments.md * guide: link from Exp Mgmt index to Sharing * guide: ~~isolate~~ from link to Exp Sharing per https://github.com/iterative/dvc.org/pull/2711#pullrequestreview-730211648 * Update content/docs/user-guide/experiment-management/sharing-experiments.md Co-authored-by: David de la Iglesia Castro * guide: mention only SSH Git URLs support exp sharing per https://github.com/iterative/dvc.org/pull/2711#pullrequestreview-732522579 * guide: update dvc remote example in sharing exps * yarn format some files per https://app.circleci.com/pipelines/github/iterative/dvc.org/10086/workflows/9b1bf89f-a432-49f2-9a20-72fe77dd4102/jobs/10145 Co-authored-by: David de la Iglesia Castro --- content/docs/command-reference/exp/pull.md | 6 ++- content/docs/command-reference/exp/push.md | 6 ++- content/docs/command-reference/exp/run.md | 2 +- .../user-guide/experiment-management/index.md | 2 + .../sharing-experiments.md | 46 ++++++++----------- 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/content/docs/command-reference/exp/pull.md b/content/docs/command-reference/exp/pull.md index 32fee2b766..f9d3e5aeab 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..46bcdcb2ea 100644 --- a/content/docs/command-reference/exp/push.md +++ b/content/docs/command-reference/exp/push.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/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`). diff --git a/content/docs/user-guide/experiment-management/index.md b/content/docs/user-guide/experiment-management/index.md index f7d49feafb..4a6fe96d80 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 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. diff --git a/content/docs/user-guide/experiment-management/sharing-experiments.md b/content/docs/user-guide/experiment-management/sharing-experiments.md index cd6103b019..286ac4ad57 100644 --- a/content/docs/user-guide/experiment-management/sharing-experiments.md +++ b/content/docs/user-guide/experiment-management/sharing-experiments.md @@ -1,39 +1,33 @@ # 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 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 -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) -``` +origin git@github.com:iterative/get-started-experiments.git (fetch) +origin git@github.com:iterative/get-started-experiments.git (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 +storage s3://mybucket/my-dvc-store ``` ## Uploading experiments to remotes