Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
exp: misc. guide and ref. updates (#3080)
Browse files Browse the repository at this point in the history
* ref: bring changes from #2909

* guide: bring changes from #2909

* exp: pull some changes from #2908

* ref: better explain exp apply behavior explicitly
rel. #3080 (comment)

* ref: exp apply destroys any canges
per #3080 (comment)

* ref: clarify that exp branch makes 1+ commits in the exp branch
rel. #3080 (comment)

* ref: link exp apply -> exp branch
per #3080 (comment)

* ref: clarify (again) what applies does specifically
per #3080 (review)

* ref: document intended apply behavior on conflicting changes
per #3080 (review)
jorgeorpinel authored and iesahin committed Apr 11, 2022
1 parent 8a94431 commit d1469c5
Showing 8 changed files with 48 additions and 41 deletions.
24 changes: 14 additions & 10 deletions content/docs/command-reference/exp/apply.md
Original file line number Diff line number Diff line change
@@ -14,22 +14,26 @@ positional arguments:

## Description

Restores an `experiment` into the workspace as long as no more Git commits have
been made after the target experiment (`HEAD` hasn't moved). The `experiment`
can be referenced by name or hash (see `dvc exp run` for details). This changes
any files (code, data, <abbr>parameters</abbr>, <abbr>metrics</abbr>, etc.)
needed to reflect the experiment conditions and results in the workspace.
Restores an `experiment` into the workspace, as long as we're on the same
project baseline (Git `HEAD`) as when the target experiment was run. The
experiment can be referenced by name or hash (see `dvc exp run` for details).

Specifically, `dvc exp apply` restores any files or directories needed to
reflect the experiment conditions and results. This means checking out files
tracked both with DVC and Git: code, raw data, <abbr>parameters</abbr>,
<abbr>metrics</abbr>, resulting artifacts, etc.

⚠️ Conflicting changes in the workspace are overwritten unless `--no-force` is
used.

This is typically used after choosing a target `experiment` with `dvc exp show`
or `dvc exp diff`, and before committing it to Git (making it
[persistent](/doc/user-guide/experiment-management#persistent-experiments)).
or `dvc exp diff`, and before committing it to Git (making it [persistent].

> Note that any [checkpoints] found in the `experiment` will **not** be
> preserved when applying and committing it. Use `dvc exp branch` instead.
Note that the history of
[checkpoints](/doc/command-reference/exp/run#checkpoints) found in the
`experiment` is **not** preserved when applying and committing it.
[persistent]: /doc/user-guide/experiment-management/persisting-experiments
[checkpoints]: /doc/user-guide/experiment-management/checkpoints

## Options

20 changes: 11 additions & 9 deletions content/docs/command-reference/exp/branch.md
Original file line number Diff line number Diff line change
@@ -15,26 +15,28 @@ positional arguments:

## Description

Makes a named Git
[`branch`](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
containing the target `experiment` (making it
[persistent](/doc/user-guide/experiment-management#persistent-experiments)). For
[checkpoint experiments](/doc/command-reference/exp/run#checkpoints), the new
branch will contain multiple commits (the checkpoints).
Makes a given Git [`branch`] containing the target `experiment`. This makes the
experiment into a [regular commit], or several in the case of [checkpoint
experiments] (one per checkpoint).

The new `branch` will be based on the experiment's parent commit (`HEAD` at the
time that the experiment was run). Note that DVC **does not** switch into the
new `branch` automatically.

`dvc exp branch` is useful to make an experiment persistent without modifying
the workspace, so they can be continued,
[stored, and shared](https://dvc.org/doc/use-cases/sharing-data-and-model-files)
in a normal Git + DVC workflow.
the workspace, so they can be continued, [stored and shared] in a normal Git +
DVC workflow.

To switch into the new branch, use `git checkout branch` and `dvc checkout`. Or
use `git merge branch` and `dvc repro` to combine it with your current project
version.

[`branch`]:
https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
[regular commit]: /doc/user-guide/experiment-management/persisting-experiments
[checkpoint experiments]: /doc/command-reference/exp/run#checkpoints
[stored and shared]: /doc/use-cases/sharing-data-and-model-files

## Options

- `-h`, `--help` - shows the help message and exit.
2 changes: 1 addition & 1 deletion content/docs/command-reference/exp/run.md
Original file line number Diff line number Diff line change
@@ -44,7 +44,7 @@ name like `exp-bfe64` by default, which can be customized using the `--name`
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>
24 changes: 12 additions & 12 deletions content/docs/sidebar.json
Original file line number Diff line number Diff line change
@@ -132,18 +132,6 @@
}
]
},
{
"label": "How To",
"slug": "how-to",
"source": false,
"children": [
"stop-tracking-data",
"update-tracked-data",
"add-deps-or-outs-to-a-stage",
"merge-conflicts",
"share-a-dvc-cache"
]
},
{
"label": "Experiment Management",
"slug": "experiment-management",
@@ -158,6 +146,18 @@
"checkpoints"
]
},
{
"slug": "how-to",
"source": false,
"children": [
"stop-tracking-data",
"update-tracked-data",
"add-deps-or-outs-to-a-stage",
"merge-conflicts",
"share-a-dvc-cache",
"share-many-experiments"
]
},
"setup-google-drive-remote",
"large-dataset-optimization",
"external-dependencies",
Original file line number Diff line number Diff line change
@@ -385,8 +385,8 @@ params.yaml train.epochs 10 10 0
## Compare an experiment with the workspace

When you want to compare two experiments, either the baseline experiment in a
commit, branch, tag or an attached experiment with ID, you can supply their
names to `dvc exp diff`.
commit, branch, or tag; or an attached experiment by name, you can supply any of
these references to `dvc exp diff`.

```
$ dvc exp diff cnn-128 cnn-64
4 changes: 2 additions & 2 deletions content/docs/user-guide/experiment-management/index.md
Original file line number Diff line number Diff line change
@@ -47,8 +47,8 @@ main alternatives:

- **Git tags and branches** - use the repo's "time dimension" to distribute your
experiments. This makes the most sense for experiments that build on each
other. Helpful if the Git [revisions](https://git-scm.com/docs/revisions) can
be easily visualized, for example with tools
other. Git-based experiment structures are especially helpful along with Git
history exploration tools
[like GitHub](https://docs.github.com/en/github/visualizing-repository-data-with-graphs/viewing-a-repositorys-network).

- **Directories** - the project's "space dimension" can be structured with
Original file line number Diff line number Diff line change
@@ -134,7 +134,7 @@ $ cat .dvc/cache/6f/db5336fce0dbfd669f83065f107551.dir

That's how DVC knows that the other two cached files belong in the directory.

### Run-cache
## Run-cache

`dvc exp run` and `dvc repro` by default populate and reutilize a log of stages
that have been run in the project. It is found in the `runs/` directory inside
9 changes: 5 additions & 4 deletions content/docs/user-guide/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -92,16 +92,17 @@ using:
$ dvc checkout --relink
```

## HTTP Git authentication is not supported {#git-auth}
## DVC can only authenticate with Git remotes using SSH URLs {#git-auth}

[Experiment sharing](/doc/user-guide/experiment-management/sharing-experiments)
commands accept a `git_remote` argument. In order to access the Git remote, you
may need to authenticate for _write_ (`dvc exp push`) or _read_ (`dvc exp list`,
commands accept a `git_remote` argument. You may need to authenticate to use the
Git remote, for _write_ (`dvc exp push`) or _read_ (`dvc exp list`,
`dvc exp pull`) permissions.

DVC does not currently support authentication with [Git credentials]. This means
that unless the Git server allows unauthenticated HTTP write/read, you should
use an [SSH Git URL] when listing, pulling or pushing experiments.
use an [SSH Git URL] for Git remotes used for listing, pulling or pushing
experiments.

[git credentials]: https://git-scm.com/docs/gitcredentials
[ssh git url]:

0 comments on commit d1469c5

Please sign in to comment.