cache/CACHING.md

# Cache Recipes

This document focuses on gathering all the common use cases that will help the users of `actions/cache`
- Know the use cases that can be tackled and sample workflows on how to tackle them
- Optimise their workflows to use the cache inputs and outputs better

## Actions Cache Basics

The cache action works using the following set of inputs and outputs as mentioned [here](https://github.com/actions/cache#inputs). However these inputs are self explaining below are some ways in which the inputs can be used in a better way.

### Keys

A `key`, also referred as `primary key` is a value with which cache is restored or saved. If cache is not found with the primary key, the same key is used to save the cache in the `actions/cache` action.
#### Static keys

```yaml
    - uses: actions/cache@v3
      with:
        key: static-key
```

In your workflows, you can use keys in a hardcoded manner. This way the same `key` will be saved once and restored till its evicted. In case the `key` gets evicted, cache with same `key` will be created again and saved.

#### Dynamic keys

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    - uses: actions/cache@v3
      with:
        key: ${{ runner.os }}-cache
```

In your workflows, if you wish to create OS specific caches, or caches based on the lockfiles, commit SHA, workflow run id, etc. then you can generate the keys dynamically at run-time. Below are some of the ways to use dynamically generated keys

Cache key by Operating system: 
```yaml
    key: ${{ runner.os }}-cache
```
Cache key by Workflow run id/attempt: 
```yaml
    key: cache-${{ github.run_id }}-${{ github.run_attempt }}
```
Cache key by commit id: 
```yaml
    key: cache-${{ github.sha }}
```
Cache key by lockfile: 
```yaml
    key: cache-${{ hashFiles('**/lockfiles') }}
```
Cache key by combination of multiple options: 
```yaml
    key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```

The [GitHub Context](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) can be used to create keys using the workflows metadata.

### Restore keys

Restore keys are a set of keys that are looked for when cache with primary key is not found. The first matching cache is downloaded when restore keys are provided.

The restore keys can be provided as a complete name, or a prefix, read more [here](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) on how a cache key is matched using restore keys.

### Paths

The path(s) in the cache action define(s) the path/directory that needs to be cached. The directory can reside on the runner or containers inside runners. The path to dependencies can either be a fix path or a glob pattern that's matched with existing directory structure and evaluated at runtime. Refer [@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob#patterns) to get more information about the patterns.

Examples:

<!-- TODO: add all possible paths examples here along with any env vars / context vars-->

### Version

Cache version is a hash generated for a combination of compression tool used (Gzip, Zstd, etc. based on the runner OS) and the path of directories being cached. If two caches have different versions, they are identified as unique caches while matching. This for example, means that a cache created on `windows-latest` runner may not be restored on `ubuntu-latest` as cache versions could be different.

> TL;DR 
Version = hash(Compression tool, Path(s) to be cached)

### Branch

Whenever a cache is saved, the repository `branch` where it was generated is also stored along with it. This is done mainly to avoid caches from `feature` branches to interact with jobs running on the `default` branch. 

### Scope

The cache is scoped to a key, version and branch. The default branch cache is accessible to all other branches, but not the other way round. This means if you have a cache with key matching (completely or partially) and (exact) version in the default branch, you will be able to restore the cache in any of the branches. However if you create a cache in a feature branch, it cannot be restored in any other branch.
Refer [matching the key](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) for more info on how keys are matched and restored.

## Cache action

The cache action allows caching dependencies and build outputs to improve workflow execution time.

It has a `main` step and a `post` step. In the `main` step, the cache is restored if it exists for the input `key`, `path` combination (refer [scope](#scope)). If the cache doesn't exist or a partial match is found, the cache is saved in the `post` step.

**Usage**

```yaml
  - uses: actions/cache@v3
```

### Sample workflow for cache action

## Restore action

**Usage**

```yaml
  - uses: actions/cache/restore@v3
```

### Sample workflow for restore action
<!-- Explain how the outputs differ depending on caches found, not found or partially found -->

### Restore only on cache hit (else fail the workflow)

### Make cache read only / Reuse cache from centralized job

## Save action

**Usage**

```yaml
  - uses: actions/cache/restore@v3
```

### Sample workflow for save action
<!-- Explain the different ways of taking the inputs here 
Saving with hardcoded key - Basic save
Saving with key outputted from restore action
Saving with key re-evaluated at save step
-->

## Restore followed by save

<!--
Basic restore save example
- Using default cache action
- Using restore and save actions together with possibilities.
Restore save example with advanced controls
- Using if conditions to achieve use cases that we solved 
- Fail workflow on cache miss
- Force rewrite cache by deleting cache between steps using cli
-->

## Save followed by restore
<!--
- Use case for saving first and restoring across child/subsequent jobs
- A complex workflow with save and restore actions called multiple times.
- Save cache on any failure.
-->

## Storage & CLI

<!--
Mention about the storage quota
UI - how it can be used to view the storage info
CLI - how it can be used in workflows to take care of the cache storage and management
-->

## Optimisation

<!-- 
1. Key optimisation examples - create good keys to get more cache match.
2. Storage optimisation examples - avoid recreation of caches whenever not needed.
3. Branch optimisation examples where cache can be restored from default branches but need not be stored for feature branches
4. Cross OS?
-->

## Snippets

<!-- Similar to available in README but updating set-output method and adding new package managers. -->