What does restore-keys do?

[nchammas]

The README says:

restore-keys - An ordered list of keys to use for restoring the cache if no cache hit occurred for key

I don't understand what this means. If there is no hit on key, then that means any previous caches are likely not useful (e.g. because our dependencies have changed). So what cache is there to restore when key has changed?

Looking at the pip example, for example, I don't follow what this part is doing for us:

    restore-keys: |
      ${{ runner.os }}-pip-

What do we lose if we remove that part from the Action inputs? Can someone illustrate with an example scenario?

[domjtalbot]

Hey @nchammas!

The restore-keys option works as a backup for when the specific cache key you want doesn't return any results.

For instance a minimal setup could look like this:

- uses: actions/cache@v2
   with:
     path: ~/.cache/pip
     key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

In this example, we're requesting that ~/.cache/pip is cached using the key provided which could look like Linux-pip-8156c. However, the cache will only be restored if the key is a perfect match. This might be exactly what you want it to do, but you might also want it to restore another cache as a backup, which is where restore-keys comes into play!

- uses: actions/cache@v2
   with:
     path: ~/.cache/pip
     key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
     restore-keys: |
       ${{ runner.os }}-pip-

With the addition of restore-keys, now if no cache matches our key perfectly, we have defined what cache to use as a backup. For example, if no cache exists for our key Linux-pip-8156c, then we'll try to restore another cache using the key Linux-pip- as backup (if any exists).

I hope that helps!

[nchammas]

I guess the idea is that, even though the backup cache won't be a perfect match, it will still help. Right?

When is this backup cache actually populated? Is it simply a copy of the primary cache?

[domjtalbot]

Yeh, that's right. It might not be perfect, but depending on your workflow, it may help a lot.

The 'backup' is a previously saved cache. Each time your primary cache key changes a new cache is created.

In the previous example, our cache key was Linux-pip-8156c, but if we then made a change to the requirements.txt file, the cache key would then be different on the next build - let's say it's now Linux-pip-5198l. This is because we're using hashFiles to generate a unique hash number from **/requirements.txt. So we now have two sets of cache saved:

• Linux-pip-8156c (old)
• Linux-pip-5198l (latest)

If we then made a change to README.md, the cache key would remain the same as before (Linux-pip-5198l) and the cache (Linux-pip-5198l) would be restored.

If we then made another change to requirements.txt, the cache key would change - let's say it's now Linux-pip-7521p - meaning there would be no cache to restore. But of course, this is where our restore key helps us out (Linux-pip-). It might help to think about the restore key as a wildcard (Linux-pip-*), where it will match the first existing cache key it finds. In this example, the cache returned as a backup would be Linux-pip-5198l.

After the current workflow completes, we'll have 3 saved caches:

• Linux-pip-8156c (old)
• Linux-pip-5198l (old)
• Linux-pip-7521p (latest)

If we were then to make yet another change to requirements.txt, the cache key would change again and this time the restore key would return Linux-pip-7521p as a backup. And the cycle continues. 😄