Add documentation for new big-repos featuresupdate-custom-build-dir-docs

This adds documentation for:

- `CI_BUILDS_DIR`,
- `CI_CONCURRENT_ID`,
- `CI_CONCURRENT_PROJECT_ID`,
- `GIT_CLONE_PATH`,
- `GIT_CLEAN_FLAGS`

2 files changed, 94 insertions, 2 deletions

diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index 416627740d2..a02b5e786df 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -23,6 +23,9 @@ future GitLab releases.**
 | `CHAT_INPUT`                            | 10.6   | all    | Additional arguments passed in the [ChatOps](../chatops/README.md) command |
 | `CHAT_CHANNEL`                          | 10.6   | all    | Source chat channel which triggered the [ChatOps](../chatops/README.md) command |
 | `CI`                                    | all    | 0.4    | Mark that job is executed in CI environment |
+| `CI_BUILDS_DIR`                         | all    | 11.10  | The top-level directory where are builds are being executed |
+| `CI_CONCURRENT_ID`                      | all    | 11.10  | The unique ID of build execution within single executor |
+| `CI_CONCURRENT_PROJECT_ID`              | all    | 11.10  | The unique ID of build execution within single executor and project ID |
 | `CI_COMMIT_BEFORE_SHA`                  | 11.2   | all    | The previous latest commit present on a branch before a push request. |
 | `CI_COMMIT_DESCRIPTION`                 | 10.8   | all    | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. |
 | `CI_COMMIT_MESSAGE`                     | 10.8   | all    | The full commit message. |
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index e75f7050a09..966d16a8f54 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -2341,8 +2341,33 @@ variables:
   GIT_STRATEGY: clone
   GIT_CHECKOUT: "false"
 script:
-  - git checkout master
-  - git merge $CI_BUILD_REF_NAME
+  - git checkout -B master origin/master
+  - git merge $CI_COMMIT_SHA
+```
+
+#### Git clean flags
+
+> Introduced in GitLab Runner 11.10
+
+The `GIT_CLEAN_FLAGS` variable can be used to control a default behavior of
+`git clean` after checking out the sources. You can set them globally or per-job in the
+[`variables`](#variables) section.
+
+The `GIT_CLEAN_FLAGS` accepts all possible options of the [git clean](https://git-scm.com/docs/git-clean)
+command.
+
+The `git clean` is disabled if `GIT_CHECKOUT: "false"` is specified.
+
+Consider the following predefined behavior:
+
+- if not specified it defaults to `-ffdx`,
+- if `none` specified it makes the `git clean` command not being executed
+
+```yaml
+variables:
+  GIT_CLEAN_FLAGS: -ffdx -e cache/
+script:
+  - ls -al cache/
 ```
 
 #### Job stages attempts
@@ -2418,6 +2443,69 @@ CAUTION: **Deprecated:**
 `type` is deprecated, and could be removed in one of the future releases.
 Use [`stage`](#stage) instead.
 
+### Custom build directories
+
+> [Introduced][gitlab-runner-1267] in Gitlab Runner 11.10
+
+NOTE: **Note:**
+This can only be used when `custom_build_dir` is enabled in the [Runner's
+configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section).
+This is the default configuration for `docker` and `kubernetes` executor.
+
+By default, GitLab Runner clones the repository in unique subpath of the `$CI_BUILDS_DIR` directory,
+but sometimes your project might require to have the code in a specific directory,
+like the Go projects for example. In that case, you can specify the `GIT_CLONE_PATH` variable
+to tell the Runner in which directory to clone the repository:
+
+```yml
+variables:
+  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name
+
+test:
+  script:
+    - pwd
+```
+
+The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The `$CI_BUILDS_DIR`
+is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
+setting.
+
+Consider that if you executor uses higher than `1` concurrency it might lead
+to failures as multiple jobs might be working on the same directory, if the `builds_dir`
+is shared between jobs.
+GitLab Runner does not try to prevent that situation it is up to Administrator
+and Developer to comply with the requirements of runner configuration.
+
+To avoid such scenario you can use unique path within `$CI_BUILDS_DIR`, as Runner
+exposes two additional variables that provide a unique `ID` of concurrency:
+
+- `$CI_CONCURRENT_ID`: unique identifier for all jobs running within the given executor,
+- `$CI_CONCURRENT_PROJECT_ID`: unique identifier for all jobs running within the given executor and project.
+
+The most stable configuration that should work well in any scenario and on any executor
+is to use `$CI_CONCURRENT_ID`:
+
+```yml
+variables:
+  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name
+
+test:
+  script:
+    - pwd
+```
+
+The `$CI_CONCURRENT_PROJECT_ID` should be used with the conjuction of `$CI_PROJECT_PATH`
+as the `$CI_PROJECT_PATH` provides a path of repository: `group/subgroup/project`.
+
+```yml
+variables:
+  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH
+
+test:
+  script:
+    - pwd
+```
+
 ## Special YAML features
 
 It's possible to use special YAML features like anchors (`&`), aliases (`*`)
@@ -2604,3 +2692,4 @@ git push -o ci.skip
 [schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules"
 [variables]: ../variables/README.md "CI/CD variables"
 [push-option]: https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt
+[gitlab-runner-1267]: https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267