Merge branch 'ci-git' into 'master'

Document `GIT_STRATEGY` and `GIT_DEPTH`

## What does this MR do?

Documents `GIT_STRATEGY` and `GIT_DEPTH`. Also fixes the TOC since the anchors weren't working.

## Are there points in the code the reviewer needs to double check?

The TOC and the location of the new entries.

## Why was this MR needed?

## What are the relevant issue numbers?

https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/merge_requests/188

## Screenshots (if relevant)

![image](/uploads/eccfd60199d81e6588c13aab817f0eb5/image.png)

![image](/uploads/bbbffe61db64ef17f1fa52907275f3d4/image.png)

/cc @axil @ayufan

See merge request !4720
Signed-off-by: Rémy Coutable <remy@rymai.me>

CHANGELOG

@@ -3,6 +3,7 @@ Please view this file on the master branch, on stable branches it's out of date.
 v 8.9.1 (unreleased)
   - Refactor labels documentation. !3347
   - Fix some CI wording in documentation. !4660
+  - Document `GIT_STRATEGY` and `GIT_DEPTH`. !4720
   - Fix MR-auto-close text added to description. !4836
   - Fix typo in export failure email. !4847
 

doc/ci/yaml/README.md

@@ -24,21 +24,23 @@ If you want a quick introduction to GitLab CI, follow our
 - [Jobs](#jobs)
   - [script](#script)
   - [stage](#stage)
-    - [job variables](#job-variables)
   - [only and except](#only-and-except)
+  - [job variables](#job-variables)
   - [tags](#tags)
   - [when](#when)
   - [environment](#environment)
   - [artifacts](#artifacts)
-        - [artifacts:name](#artifacts-name)
-        - [artifacts:when](#artifacts-when)
-        - [artifacts:expire_in](#artifacts-expire_in)
+    - [artifacts:name](#artifactsname)
+    - [artifacts:when](#artifactswhen)
+    - [artifacts:expire_in](#artifactsexpire_in)
   - [dependencies](#dependencies)
   - [before_script and after_script](#before_script-and-after_script)
+- [Git Strategy](#git-strategy)
+- [Shallow cloning](#shallow-cloning)
 - [Hidden jobs](#hidden-jobs)
 - [Special YAML features](#special-yaml-features)
   - [Anchors](#anchors)
-- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ci-yml)
+- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ciyml)
 - [Skipping builds](#skipping-builds)
 - [Examples](#examples)
 
@@ -821,6 +823,61 @@ job:
   - execute this after my script
 ```
 
+## Git Strategy
+
+>**Note:**
+Introduced in GitLab 8.9 as an experimental feature. May change in future
+releases or be removed completely.
+
+You can set the `GIT_STRATEGY` used for getting recent application code. `clone`
+is slower, but makes sure you have a clean directory before every build. `fetch`
+is faster. `GIT_STRATEGY` can be specified in the global `variables` section or
+in the `variables` section for individual jobs. If it's not specified, then the
+default from project settings will be used.
+
+```
+variables:
+  GIT_STRATEGY: clone
+```
+
+or
+
+```
+variables:
+  GIT_STRATEGY: fetch
+```
+
+## Shallow cloning
+
+>**Note:**
+Introduced in GitLab 8.9 as an experimental feature. May change in future
+releases or be removed completely.
+
+You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows
+shallow cloning of the repository which can significantly speed up cloning for
+repositories with a large number of commits or old, large binaries. The value is
+passed to `git fetch` and `git clone`.
+
+>**Note:**
+If you use a depth of 1 and have a queue of builds or retry
+builds, jobs may fail.
+
+Since Git fetching and cloning is based on a ref, such as a branch name, runners
+can't clone a specific commit SHA. If there are multiple builds in the queue, or
+you are retrying an old build, the commit to be tested needs to be within the
+git history that is cloned. Setting too small a value for `GIT_DEPTH` can make
+it impossible to run these old commits. You will see `unresolved reference` in
+build logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
+
+Builds that rely on `git describe` may not work correctly when `GIT_DEPTH` is
+set since only part of the git history is present.
+
+To fetch or clone only the last 3 commits:
+```
+variables:
+  GIT_DEPTH: "3"
+```
+
 ## Hidden jobs
 
 >**Note:**