Commit f81259d1 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Rémy Coutable

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: default avatarRémy Coutable <remy@rymai.me>
parent bdaced56
......@@ -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
......
......@@ -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:**
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment