Skip to content

Commit

Permalink
guide: consolidate Exp Sharing intro (#2711)
Browse files Browse the repository at this point in the history
* 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 #2711 (review)

* Update content/docs/user-guide/experiment-management/sharing-experiments.md

Co-authored-by: David de la Iglesia Castro <[email protected]>

* guide: mention only SSH Git URLs support exp sharing
per #2711 (review)

* 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 <[email protected]>
  • Loading branch information
jorgeorpinel and daavoo authored Aug 18, 2021
1 parent fb4663c commit d1422b1
Show file tree
Hide file tree
Showing 5 changed files with 31 additions and 31 deletions.
6 changes: 4 additions & 2 deletions content/docs/command-reference/exp/pull.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@ positional arguments:

## Description

The `dvc exp push` and `dvc exp pull` commands are the means for sharing
experiments across <abbr>repository</abbr> copies via Git (and DVC) remotes.
The `dvc exp push` and `dvc exp pull` commands are the means for [sharing
experiments] across <abbr>repository</abbr> 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
Expand Down
6 changes: 4 additions & 2 deletions content/docs/command-reference/exp/push.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@ positional arguments:

## Description

The `dvc exp push` and `dvc exp pull` commands are the means for sharing
experiments across <abbr>repository</abbr> copies via Git (and DVC) remotes.
The `dvc exp push` and `dvc exp pull` commands are the means for [sharing
experiments] across <abbr>repository</abbr> 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
Expand Down
2 changes: 1 addition & 1 deletion content/docs/command-reference/exp/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`).

</details>
Expand Down
2 changes: 2 additions & 0 deletions content/docs/user-guide/experiment-management/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<abbr>repository</abbr> 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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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 [email protected]:iterative/get-started-experiments.git (fetch)
origin [email protected]: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
Expand Down

0 comments on commit d1422b1

Please sign in to comment.