Can someone please help me understand how the cache keys work in the Cache Action?

Here are the things I do not fully understand.

1. In some places, I see people using the “github.sha” as part of the cache key. For example:

   key: ${{ runner.os }}-docker-${{ github.sha }}
   restore-keys: |
   ${{ runner.os }}-docker-

So, as I understand it, the cache key will change with every commit, and therefore, not be a “cache hit”. What reason is there to use the commit sha in the cache key?

2. What are restore keys

The documentation on restore-keys states that there are “fallback keys” if no cache hit occurred. So does it mean that when caching is done, it will be cached using two keys, and the topmost key will be selected on restore? Or, is the “restore-keys” option actually listing prefixes of keys, so its meaning is more like “${{ runner.os }}-docker- *”?

If the answer is the latter, then it explains the first question as well, at least to some extent.

If these are not prefixes, then why is everybody using a trailing hyphen in the restore key names?

3. Restore key documentation

A quote from the restore key documentaiton:

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

But the syntax everywhere, is actually used like this:

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

which is not an ordered list, but rather a newline delimited string. I expected the syntax to match the definition (and actually be an oordered list), which makes more sense to me here:

restore-keys:
  - ${{ runner.os }}-docker-
  - ${{ runner.os }}-

What is the reason for this variable typed as a newline delimited string, instead of a proper YAML array?

Sorry for the long post, hoping someone has the patience to elaborate, and if this is you - thanks in advance!