Merge branch 'docs-deduplicate-git-strategy' into 'master'

Docs: Deduplicate GIT_STRATEGY details

See merge request gitlab-org/gitlab!46536

doc/ci/large_repositories/index.md

@@ -56,24 +56,11 @@ test:
 
 > Introduced in GitLab Runner 8.9.
 
-By default, GitLab is configured to always prefer the `GIT_STRATEGY: fetch` strategy.
-The `GIT_STRATEGY: fetch` strategy will re-use existing worktrees if found
-on disk. This is different to the `GIT_STRATEGY: clone` strategy
-as in case of clones, if a worktree is found, it is removed before clone.
-
-Usage of `fetch` is preferred because it reduces the amount of data to transfer and
+By default, GitLab is configured to use the [`fetch` Git strategy](../runners/README.md#git-strategy),
+which is recommended for large repositories.
+This strategy reduces the amount of data to transfer and
 does not really impact the operations that you might do on a repository from CI.
 
-However, `fetch` does require access to the previous worktree. This works
-well when using the `shell` or `docker` executor because these
-try to preserve worktrees and try to re-use them by default.
-
-This does not work today for `kubernetes` executor and has limitations when using
-`docker+machine`. `kubernetes` executor today always clones into ephemeral directory.
-
-GitLab also offers the `GIT_STRATEGY: none` strategy. This disables any `fetch` and `checkout` commands
-done by GitLab, requiring you to do them.
-
 ## Git clone path
 
 > Introduced in GitLab Runner 11.10.

doc/ci/pipelines/settings.md

@@ -26,10 +26,11 @@ There are two options. Using:
 
 - `git clone`, which is slower since it clones the repository from scratch
   for every job, ensuring that the local working copy is always pristine.
-- `git fetch`, which is faster as it re-uses the local working copy (falling
+- `git fetch`, which is GitLab's default and faster as it re-uses the local working copy (falling
   back to clone if it doesn't exist).
+  This is recommended, especially for [large repositories](../large_repositories/index.md#git-strategy).
 
-The default Git strategy can be overridden by the [GIT_STRATEGY variable](../runners/README.md#git-strategy)
+The configured Git strategy can be overridden by the [`GIT_STRATEGY` variable](../runners/README.md#git-strategy)
 in `.gitlab-ci.yml`.
 
 ## Git shallow clone

doc/ci/runners/README.md

@@ -478,46 +478,43 @@ You can also use variables to configure how many times a runner
 > - Introduced in GitLab 8.9 as an experimental feature.
 > - `GIT_STRATEGY=none` requires GitLab Runner v1.7+.
 
-You can set the `GIT_STRATEGY` used for getting recent application code, either
-globally or per-job in the [`variables`](../yaml/README.md#variables) section. If left
-unspecified, the default from the project settings is used.
-
-There are three possible values: `clone`, `fetch`, and `none`.
-
-`clone` is the slowest option. It clones the repository from scratch for every
-job, ensuring that the local working copy is always pristine.
+You can set the `GIT_STRATEGY` used to fetch the repository content, either
+globally or per-job in the [`variables`](../yaml/README.md#variables) section:
 
 ```yaml
 variables:
   GIT_STRATEGY: clone
 ```
 
+There are three possible values: `clone`, `fetch`, and `none`. If left unspecified,
+jobs use the [project's pipeline setting](../pipelines/settings.md#git-strategy).
+
+`clone` is the slowest option. It clones the repository from scratch for every
+job, ensuring that the local working copy is always pristine.
+If an existing worktree is found, it is removed before cloning.
+
 `fetch` is faster as it re-uses the local working copy (falling back to `clone`
 if it does not exist). `git clean` is used to undo any changes made by the last
-job, and `git fetch` is used to retrieve commits made since the last job ran.
+job, and `git fetch` is used to retrieve commits made after the last job ran.
 
-```yaml
-variables:
-  GIT_STRATEGY: fetch
-```
+However, `fetch` does require access to the previous worktree. This works
+well when using the `shell` or `docker` executor because these
+try to preserve worktrees and try to re-use them by default.
 
-`none` also re-uses the local working copy. However, it skips all Git operations,
-including GitLab Runner's pre-clone script, if present.
+This has limitations when using the [Docker Machine executor](https://docs.gitlab.com/runner/executors/docker_machine.html).
 
-It's useful for jobs that operate exclusively on artifacts, like a deployment job.
-Git repository data may be present, but it's likely out-of-date. You should only
-rely on files brought into the local working copy from cache or artifacts.
+It does not work for [the `kubernetes` executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
+but a [feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847) exists.
+The `kubernetes` executor always clones into an temporary directory.
 
-```yaml
-variables:
-  GIT_STRATEGY: none
-```
+A Git strategy of `none` also re-uses the local working copy, but skips all Git
+operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped,
+if present. This strategy could mean you need to add `fetch` and `checkout` commands
+to [your `.gitlab-ci.yml` script](../yaml/README.md#script).
 
-NOTE: **Note:**
-`GIT_STRATEGY` is not supported for
-[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
-but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847)
-for updates.
+It can be used for jobs that operate exclusively on artifacts, like a deployment job.
+Git repository data may be present, but it's likely out of date. You should only
+rely on files brought into the local working copy from cache or artifacts.
 
 ### Git submodule strategy