Commit e5a60274 authored by Marius Bobin's avatar Marius Bobin Committed by Marcel Amirault

Add use case content for CI cache key documentation

parent ec487188
...@@ -1539,9 +1539,14 @@ cache: ...@@ -1539,9 +1539,14 @@ cache:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18986) in GitLab v12.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18986) in GitLab v12.5.
If `cache:key:files` is added, one or two files must be defined with it. The cache `key` The `cache:key:files` keyword extends the `cache:key` functionality by making it easier
will be a SHA computed from the most recent commits (one or two) that changed the to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline
given files. If neither file was changed in any commits, the key will be `default`. runs.
When you include `cache:key:files`, you must also list the project files that will be used to generate the key, up to a maximum of two files.
The cache `key` will be a SHA checksum computed from the most recent commits (up to two, if two files are listed)
that changed the given files. If neither file was changed in any commits,
the fallback key will be `default`.
```yaml ```yaml
cache: cache:
...@@ -1554,20 +1559,26 @@ cache: ...@@ -1554,20 +1559,26 @@ cache:
- node_modules - node_modules
``` ```
In this example we are creating a cache for Ruby and Nodejs dependencies that
is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of
these files changes, a new cache key is computed and a new cache is created. Any future
job runs using the same `Gemfile.lock` and `package.json` with `cache:key:files` will
use the new cache, instead of rebuilding the dependencies.
##### `cache:key:prefix` ##### `cache:key:prefix`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18986) in GitLab v12.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18986) in GitLab v12.5.
The `prefix` parameter adds extra functionality to `key:files` by allowing the key to The `prefix` parameter adds extra functionality to `key:files` by allowing the key to
be composed of the given `prefix` combined with the SHA computed for `cache:key:files`. be composed of the given `prefix` combined with the SHA computed for `cache:key:files`.
For example, adding a `prefix` of `rspec`, will For example, adding a `prefix` of `test`, will cause keys to look like: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`.
cause keys to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`. If neither If neither file was changed in any commits, the prefix is added to `default`, so the
file was changed in any commits, the prefix is added to `default`, so the key in the key in the example would be `test-default`.
example would be `rspec-default`.
`prefix` follows the same restrictions as `key`, so it can use any of the Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md),
[predefined variables](../variables/README.md). Similarly, the `/` character or the but the following are not allowed:
equivalent URI-encoded `%2F`, or a value made only of `.` or `%2E`, is not allowed.
- the `/` character (or the equivalent URI-encoded `%2F`)
- a value made only of `.` (or the equivalent URI-encoded `%2E`)
```yaml ```yaml
cache: cache:
...@@ -1577,8 +1588,20 @@ cache: ...@@ -1577,8 +1588,20 @@ cache:
prefix: ${CI_JOB_NAME} prefix: ${CI_JOB_NAME}
paths: paths:
- vendor/ruby - vendor/ruby
rspec:
script:
- bundle exec rspec
``` ```
For example, adding a `prefix` of `$CI_JOB_NAME` will
cause the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and
the job cache is shared across different branches. If a branch changes
`Gemfile.lock`, that branch will have a new SHA checksum for `cache:key:files`. A new cache key
will be generated, and a new cache will be created for that key.
If `Gemfile.lock` is not found, the prefix is added to
`default`, so the key in the example would be `rspec-default`.
#### `cache:untracked` #### `cache:untracked`
Set `untracked: true` to cache all files that are untracked in your Git Set `untracked: true` to cache all files that are untracked in your Git
......
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