user-guide: add troubleshooting entry for dvc-exp in shallow clones (#…

…3577)

* user-guide: add troubleshooting entry for dvc-exp in shallow clones

* guide: rewrite git-shallow troubleshooting

* Restyled by prettier (#3588)

Co-authored-by: Restyled.io <commits@restyled.io>

* guide: better CML mention

* some tweaks

* Restyled by prettier (#3614)

Co-authored-by: Restyled.io <commits@restyled.io>

* Apply suggestions from code review

Co-authored-by: Casper da Costa-Luis <casper.dcl@physics.org>

* Restyled by prettier (#3638)

Co-authored-by: Restyled.io <commits@restyled.io>

Co-authored-by: Jorge Orpinel <jorgeorpinel@users.noreply.github.com>
Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com>
Co-authored-by: Restyled.io <commits@restyled.io>
Co-authored-by: Casper da Costa-Luis <casper.dcl@physics.org>

content/docs/user-guide/troubleshooting.md

@@ -125,3 +125,63 @@ and retry the DVC command. Specifically, one of:
 
 [internal directories]:
   https://dvc.org/doc/user-guide/project-structure/internal-files
+
+## DVC Experiments may fail in Git shallow clones {#git-shallow}
+
+`dvc exp` commands use internal Git operations which may not work properly in
+[shallow clones](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt).
+Local Git repositories can be unshallowed with `git fetch --unshallow`.
+
+This often occurs in transient remote environments such as Continuous
+Integration (CI) jobs, which use shallow clones by default. In those cases,
+change their configuration to avoid shallow cloning. Common examples:
+
+<toggle>
+<tab title="CML">
+
+[CML](https://cml.dev) has a convenient `--unshallow` option for its
+[`ci`](https://cml.dev/doc/ref/ci) command:
+
+```cli
+$ cml ci --unshallow
+```
+
+</tab>
+<tab title="GitHub Actions">
+
+Set `fetch-depth` to `0` in the `actions/checkout` action:
+
+```yaml
+- uses: actions/checkout@v3
+  with:
+    fetch-depth: 0
+```
+
+<admon type="info">
+
+See the
+[GitHub Actions docs](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches)
+for more information.
+
+</admon>
+
+</tab>
+<tab title="GitLab CI/CD">
+
+Set the `GIT_DEPTH` env var to `0`:
+
+```yaml
+variables:
+  GIT_DEPTH: '0'
+```
+
+<admon type="info">
+
+See the
+[GitLab CI/CD docs](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning)
+for more information.
+
+</admon>
+
+</tab>
+</toggle>