diff --git a/content/docs/command-reference/exp/apply.md b/content/docs/command-reference/exp/apply.md
index 1bc6b16767..e482aa4b3f 100644
--- a/content/docs/command-reference/exp/apply.md
+++ b/content/docs/command-reference/exp/apply.md
@@ -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, parameters, metrics, 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, parameters,
+metrics, 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
diff --git a/content/docs/command-reference/exp/branch.md b/content/docs/command-reference/exp/branch.md
index a4ac9a4c11..cdbc88f747 100644
--- a/content/docs/command-reference/exp/branch.md
+++ b/content/docs/command-reference/exp/branch.md
@@ -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.
diff --git a/content/docs/command-reference/exp/run.md b/content/docs/command-reference/exp/run.md
index 869f9a7b8a..4dd24b6896 100644
--- a/content/docs/command-reference/exp/run.md
+++ b/content/docs/command-reference/exp/run.md
@@ -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`).
diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json
index 995ed6f3bd..48e0e20f27 100644
--- a/content/docs/sidebar.json
+++ b/content/docs/sidebar.json
@@ -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",
diff --git a/content/docs/user-guide/experiment-management/comparing-experiments.md b/content/docs/user-guide/experiment-management/comparing-experiments.md
index 93dc87e173..8c753a81dc 100644
--- a/content/docs/user-guide/experiment-management/comparing-experiments.md
+++ b/content/docs/user-guide/experiment-management/comparing-experiments.md
@@ -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
diff --git a/content/docs/user-guide/experiment-management/index.md b/content/docs/user-guide/experiment-management/index.md
index b501fd0a16..b032c7e18e 100644
--- a/content/docs/user-guide/experiment-management/index.md
+++ b/content/docs/user-guide/experiment-management/index.md
@@ -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
diff --git a/content/docs/user-guide/project-structure/internal-files.md b/content/docs/user-guide/project-structure/internal-files.md
index 3a77648119..9339a385a1 100644
--- a/content/docs/user-guide/project-structure/internal-files.md
+++ b/content/docs/user-guide/project-structure/internal-files.md
@@ -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
diff --git a/content/docs/user-guide/troubleshooting.md b/content/docs/user-guide/troubleshooting.md
index 4804adb508..2eef09b77f 100644
--- a/content/docs/user-guide/troubleshooting.md
+++ b/content/docs/user-guide/troubleshooting.md
@@ -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]: