From d24e508a056e9e8a88e1cf0e91664b47e6932799 Mon Sep 17 00:00:00 2001
From: Peter Rowlands <peter@pmrowla.com>
Date: Fri, 20 May 2022 15:36:42 +0900
Subject: [PATCH] user-guide: add troubleshooting entry for dvc-exp in shallow
 clones

---
 content/docs/user-guide/troubleshooting.md | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/content/docs/user-guide/troubleshooting.md b/content/docs/user-guide/troubleshooting.md
index 2eef09b77f7..9f39bde83c4 100644
--- a/content/docs/user-guide/troubleshooting.md
+++ b/content/docs/user-guide/troubleshooting.md
@@ -107,3 +107,39 @@ experiments.
 [git credentials]: https://git-scm.com/docs/gitcredentials
 [ssh git url]:
   https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_protocols
+
+## DVC experiments may fail in shallow Git repositories {#git-shallow}
+
+DVC experiments rely on Git features which may not work properly in shallow Git
+repositories. This error commonly occurs in certain CI environments which use
+shallow git clones by default. When this error is encountered, try unshallowing
+the Git repository and then retry the DVC command.
+
+Local Git repositories can be unshallowed by using:
+
+```
+$ git fetch --unshallow
+```
+
+When using [CML](https://cml.dev/doc), repositories can be unshallowed by using:
+
+```
+$ cml ci --unshallow
+```
+
+In GitHub Actions, repositories can be unshallowed by setting `fetch-depth` in
+the `actions/checkout` action.
+
+```
+- uses: actions/checkout@v3
+  with:
+    fetch-depth: 0
+```
+
+In GitLab CI/CD, repositories can be unshallowed by setting the `GIT_DEPTH`
+environment variable:
+
+```
+variables:
+  GIT_DEPTH: "0"
+```