Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

exp: misc. guide and ref. updates #3080

Merged
merged 12 commits into from
Dec 23, 2021
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions content/docs/command-reference/exp/apply.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,25 @@ 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.
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).

⚠️ Conflicting changes in the workspace are overwritten unless `--no-force` is
used.
Specifically, `dvc exp apply` changes any files (code, data,
<abbr>parameters</abbr>, <abbr>metrics</abbr>, etc.) needed to reflect the
experiment conditions and results in the workspace. Current changes to the
workspace are preserved except if they conflict with the experiment in question.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

⚠️ Conflicting changes in the workspace are overwritten unless unless
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
`--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 if a history of [checkpoints] is found in the `experiment`, it will
> **not** be preserved when applying and committing it.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

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

Expand Down
20 changes: 11 additions & 9 deletions content/docs/command-reference/exp/branch.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
[checkpoint experiments](/doc/command-reference/exp/run#checkpoints), the new
branch will contain multiple commits (the checkpoints).
Makes a named Git [`branch`] containing the target `experiment` (making it
[persistent]. For [checkpoint experiments], the new branch will contain multiple
commits (the checkpoints).

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
[persistent]: /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.
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 @@ 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>
Expand Down
24 changes: 12 additions & 12 deletions content/docs/sidebar.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -384,8 +384,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`.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

```
$ dvc exp diff cnn-128 cnn-64
Expand Down
4 changes: 2 additions & 2 deletions content/docs/user-guide/experiment-management/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 5 additions & 4 deletions content/docs/user-guide/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]:
Expand Down