Document how a restore-key cache is chosen

[robw-mercury]

I don't see any documentation that describes which partial cache match will be chosen when there are multiple options.

Consider the following case:

Cache key pattern: {branch-name}-{content-hash} My cache key: rob-branch--5555 My cache restore keys: rob-branch-- Available caches:

• rob-branch--11111, created 1 day ago
• rob-branch--3333, created 1 minute ago
• rob-branch--4444, created 10 minutes ago

All of these match the restore pattern.

If the fallback match is based on the newest matching cache file, rob-branch--3333 will be restored. If the fallback match is based on alphabetic sorting, rob-branch--1111 will be restored. If the fallback match is based on reverse alphabetic sorting, rob-branch--4444 will be restored.

I need this information to deliver the best partial matches for incremental builds. Thanks for your help.