From c45a6bf3ba13cbd532852dfcc48ef3fd7aa545e4 Mon Sep 17 00:00:00 2001
From: Kamil Trzcinski <ayufan@ayufan.eu>
Date: Thu, 14 Jan 2016 17:52:59 +0100
Subject: Added cache:key to .gitlab-ci.yml allowing to fine tune the caching

---
 doc/ci/yaml/README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 4 deletions(-)

(limited to 'doc/ci/yaml')

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index fd0d49de4e4..3b594df659d 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -135,10 +135,9 @@ thus allowing to fine tune them.
 ### cache
 
 `cache` is used to specify a list of files and directories which should be
-cached between builds. Caches are stored according to the branch/ref and the
-job name. They are not currently shared between different job names or between
-branches/refs, which means that caching will benefit you if you push subsequent
-commits to an existing feature branch.
+cached between builds.
+
+**By default the caching is enabled per-job and per-branch.**
 
 If `cache` is defined outside the scope of the jobs, it means it is set
 globally and all jobs will use its definition.
@@ -152,6 +151,59 @@ cache:
   - binaries/
 ```
 
+#### cache:key
+
+_**Note:** Introduced in GitLab Runner v1.0.0._
+
+The `key` directive allows you to define the affinity of caching
+between jobs, allowing to have a single cache for all jobs,
+cache per-job, cache per-branch or any other way you deem proper.
+
+This allows you to fine tune caching, allowing you to cache data between different jobs or even different branches.
+The `cache:key` variable can use any of the [predefined variables](../variables/README.md):
+
+Example configurations:
+
+To enable per-job caching:
+
+    ```yaml
+    cache:
+      key: "$CI_BUILD_NAME"
+      untracked: true
+    ```
+
+To enable per-branch caching:
+
+    ```yaml
+    cache:
+      key: "$CI_BUILD_REF_NAME"
+      untracked: true
+    ```
+
+To enable per-job and per-branch caching:
+
+    ```yaml
+    cache:
+      key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
+      untracked: true
+    ```
+
+To enable per-branch and per-stage caching:
+
+    ```yaml
+    cache:
+      key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
+      untracked: true
+    ```
+
+If you use **Windows Batch** to run your shell scripts you need to replace the `$` with `%`:
+
+    ```yaml
+    cache:
+      key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
+      untracked: true
+    ```
+
 ## Jobs
 
 `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job
-- 
cgit v1.2.3


From 2254413267f69ddf2a84a37ae4c90b5cc248ec94 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Fri, 22 Jan 2016 12:33:37 +0100
Subject: Fix broken codeblocks in ci/yaml documentation

[ci skip]
---
 doc/ci/yaml/README.md | 63 +++++++++++++++++++++++++++------------------------
 1 file changed, 34 insertions(+), 29 deletions(-)

(limited to 'doc/ci/yaml')

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 3b594df659d..c8d5ecb8eef 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -159,50 +159,55 @@ The `key` directive allows you to define the affinity of caching
 between jobs, allowing to have a single cache for all jobs,
 cache per-job, cache per-branch or any other way you deem proper.
 
-This allows you to fine tune caching, allowing you to cache data between different jobs or even different branches.
-The `cache:key` variable can use any of the [predefined variables](../variables/README.md):
+This allows you to fine tune caching, allowing you to cache data between
+different jobs or even different branches.
 
-Example configurations:
+The `cache:key` variable can use any of the [predefined variables](../variables/README.md).
+
+---
+
+**Example configurations**
 
 To enable per-job caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_NAME"
+  untracked: true
+```
 
 To enable per-branch caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
 To enable per-job and per-branch caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
 To enable per-branch and per-stage caching:
 
-    ```yaml
-    cache:
-      key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
+  untracked: true
+```
 
-If you use **Windows Batch** to run your shell scripts you need to replace the `$` with `%`:
+If you use **Windows Batch** to run your shell scripts you need to replace
+`$` with `%`:
 
-    ```yaml
-    cache:
-      key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
-      untracked: true
-    ```
+```yaml
+cache:
+  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
+  untracked: true
+```
 
 ## Jobs
 
-- 
cgit v1.2.3