Update readme and examples to use v2

README.md

@@ -8,6 +8,58 @@ This action allows caching dependencies and build outputs to improve workflow ex
 
 See ["Caching dependencies to speed up workflows"](https://help.github.com/github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows).
 
+## What's New in V2
+
+* Added support for caching multiple paths,
+
+```yaml
+- name: Cache multiple relative paths
+  uses: actions/cache@v2
+  with:
+    path: |
+      node_modules
+      dist
+    key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+```
+```yaml
+- name: Cache multiple absolute paths
+  uses: actions/cache@v2
+  with:
+    path: |
+      ~/cache
+      /path/to/dependencies
+    key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+```
+
+[glob patterns](https://github.com/actions/toolkit/tree/master/packages/glob), 
+
+```yaml
+- name: Cache using glob patterns
+  uses: actions/cache@v2
+  with:
+    path: |
+      **/*.ts
+      **/node_modules
+    key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+```
+
+and single file caches. 
+
+```yaml
+- name: Cache single file
+  uses: actions/cache@v2
+  with:
+    path: cache.tar
+    key: ${{ runner.os }}
+```
+
+* Increased perfomance and improved cache sizes using `zstd` compression
+> Note this feature is off for Windows runner that are using `bsdtar` (e.g., windows-latest hosted runner) due to a bug in ziping large random files with `bsdtar`
+* Allowed caching for all events with a ref
+> See [events that trigger workflow](https://help.github.com/en/actions/reference/events-that-trigger-workflows) for info on which events do not have a `GITHUB_REF`
+* Released the [`@actions/cache`](https://github.com/actions/toolkit/tree/master/packages/cache) npm package to allow other actions to utilize caching
+* Added a best-effort cleanup step to delete the archive after extraction to reduce storage space
+
 ## Usage
 
 ### Pre-requisites
@@ -15,7 +67,8 @@ Create a workflow `.yml` file in your repositories `.github/workflows` directory
 
 ### Inputs
 
-* `path` - A directory to store and save the cache
+* `path` - Directories to store and save the cache. Supports pattern matching, multipath and single file cache
+> See [`@actions/glob`](https://github.com/actions/toolkit/tree/master/packages/glob) for supported patterns. 
 * `key` - An explicit key for restoring and saving the cache
 * `restore-keys` - An ordered list of keys to use for restoring the cache if no cache hit occurred for key
 
@@ -46,7 +99,7 @@ jobs:
 
     - name: Cache Primes
       id: cache-primes
-      uses: actions/cache@v1
+      uses: actions/cache@v2
       with:
         path: prime-numbers
         key: ${{ runner.os }}-primes
@@ -93,9 +146,11 @@ A cache key can include any of the contexts, functions, literals, and operators
 For example, using the [`hashFiles`](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#hashfiles) function allows you to create a new cache when dependencies change.
 
 ```yaml
-  - uses: actions/cache@v1
+  - uses: actions/cache@v2
     with:
-      path: path/to/dependencies
+      path: | 
+        path/to/dependencies
+        some/other/dependencies 
       key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
 ```
 
@@ -109,7 +164,7 @@ Additionally, you can use arbitrary command output in a cache key, such as a dat
       echo "::set-output name=date::$(/bin/date -u "+%Y%m%d")"
     shell: bash
 
-  - uses: actions/cache@v1
+  - uses: actions/cache@v2
     with:
       path: path/to/dependencies
       key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }}
@@ -130,7 +185,7 @@ Example:
 steps:
   - uses: actions/checkout@v2
 
-  - uses: actions/cache@v1
+  - uses: actions/cache@v2
     id: cache
     with:
       path: path/to/dependencies

examples.md

@@ -35,7 +35,7 @@
 Using [NuGet lock files](https://docs.microsoft.com/nuget/consume-packages/package-references-in-project-files#locking-dependencies):
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.nuget/packages
     key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
@@ -50,7 +50,7 @@ If you do not want to include them, consider to move the cache folder like below
 env:
   NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
 steps:
-  - uses: actions/cache@v1
+  - uses: actions/cache@v2
     with:
       path: ${{ github.workspace }}/.nuget/packages
       key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
@@ -58,12 +58,24 @@ steps:
         ${{ runner.os }}-nuget-
 ```
 
+With `actions/cache@v2` you can now exclude unwanted packages with [exclude pattern](https://github.com/actions/toolkit/tree/master/packages/glob#exclude-patterns)
+```yaml
+- uses: actions/cache@v2
+  with:
+    path: | 
+      ~/.nuget/packages
+      !~/.nuget/packages/unwanted
+    key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-nuget-
+```
+
 ## D - DUB
 
 ### POSIX
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.dub
     key: ${{ runner.os }}-dub-${{ hashFiles('**/dub.json') }}
@@ -74,7 +86,7 @@ steps:
 ### Windows
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~\AppData\Local\dub
     key: ${{ runner.os }}-dub-${{ hashFiles('**/dub.json') }}
@@ -84,7 +96,7 @@ steps:
 
 ## Elixir - Mix
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: deps
     key: ${{ runner.os }}-mix-${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}
@@ -95,7 +107,7 @@ steps:
 ## Go - Modules
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/go/pkg/mod
     key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
@@ -108,27 +120,20 @@ steps:
 We cache the elements of the Cabal store separately, as the entirety of `~/.cabal` can grow very large for projects with many dependencies.
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
-  name: Cache ~/.cabal/packages
+  name: Cache ~/.cabal/packages, ~/.cabal/store and dist-newstyle
   with:
-    path: ~/.cabal/packages
+    path: |
-    key: ${{ runner.os }}-${{ matrix.ghc }}-cabal-packages
+      ~/.cabal/packages
-- uses: actions/cache@v1
+      ~/.cabal/store
-  name: Cache ~/.cabal/store
+      dist-newstyle
-  with:
+    key: ${{ runner.os }}-${{ matrix.ghc }}
-    path: ~/.cabal/store
-    key: ${{ runner.os }}-${{ matrix.ghc }}-cabal-store
-- uses: actions/cache@v1
-  name: Cache dist-newstyle
-  with:
-    path: dist-newstyle
-    key: ${{ runner.os }}-${{ matrix.ghc }}-dist-newstyle
 ```
 
 ## Java - Gradle
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.gradle/caches
     key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
@@ -139,7 +144,7 @@ We cache the elements of the Cabal store separately, as the entirety of `~/.caba
 ## Java - Maven
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.m2/repository
     key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
@@ -156,7 +161,7 @@ For npm, cache files are stored in `~/.npm` on Posix, or `%AppData%/npm-cache` o
 ### macOS and Ubuntu
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.npm
     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
@@ -171,7 +176,7 @@ For npm, cache files are stored in `~/.npm` on Posix, or `%AppData%/npm-cache` o
   id: npm-cache
   run: |
     echo "::set-output name=dir::$(npm config get cache)"
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ${{ steps.npm-cache.outputs.dir }}
     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
@@ -186,7 +191,7 @@ For npm, cache files are stored in `~/.npm` on Posix, or `%AppData%/npm-cache` o
   id: npm-cache
   run: |
     echo "::set-output name=dir::$(npm config get cache)"
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ${{ steps.npm-cache.outputs.dir }}
     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
@@ -196,10 +201,9 @@ For npm, cache files are stored in `~/.npm` on Posix, or `%AppData%/npm-cache` o
 
 ## Node - Lerna
 
->Note this example uses the new multi-paths feature and is only available at `master`
 ```yaml
 - name: restore lerna
-  uses: actions/cache@master
+  uses: actions/cache@v2
   with:
     path: |
       node_modules
@@ -215,7 +219,7 @@ The yarn cache directory will depend on your operating system and version of `ya
   id: yarn-cache-dir-path
   run: echo "::set-output name=dir::$(yarn cache dir)"
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
   with:
     path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
@@ -229,7 +233,7 @@ Esy allows you to export built dependencies and import pre-built dependencies.
 ```yaml
     - name: Restore Cache
       id: restore-cache
-      uses: actions/cache@v1
+      uses: actions/cache@v2
       with:
         path: _export
         key:  ${{ runner.os }}-esy-${{ hashFiles('esy.lock/index.json') }}
@@ -259,7 +263,7 @@ Esy allows you to export built dependencies and import pre-built dependencies.
   id: composer-cache
   run: |
     echo "::set-output name=dir::$(composer config cache-files-dir)"
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ${{ steps.composer-cache.outputs.dir }}
     key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
@@ -278,7 +282,7 @@ Locations:
 
 ### Simple example
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.cache/pip
     key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -291,7 +295,7 @@ Replace `~/.cache/pip` with the correct `path` if not using Ubuntu.
 ### Multiple OS's in a workflow
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'Linux')
   with:
     path: ~/.cache/pip
@@ -299,7 +303,7 @@ Replace `~/.cache/pip` with the correct `path` if not using Ubuntu.
     restore-keys: |
       ${{ runner.os }}-pip-
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'macOS')
   with:
     path: ~/Library/Caches/pip
@@ -307,7 +311,7 @@ Replace `~/.cache/pip` with the correct `path` if not using Ubuntu.
     restore-keys: |
       ${{ runner.os }}-pip-
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'Windows')
   with:
     path: ~\AppData\Local\pip\Cache
@@ -326,7 +330,7 @@ Replace `~/.cache/pip` with the correct `path` if not using Ubuntu.
     echo "::set-output name=dir::$(pip cache dir)"
 
 - name: pip cache
-  uses: actions/cache@v1
+  uses: actions/cache@v2
   with:
     path: ${{ steps.pip-cache.outputs.dir }}
     key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -343,7 +347,7 @@ Replace `~/.cache/pip` with the correct `path` if not using Ubuntu.
  run: |
    python -c "from pip._internal.locations import USER_CACHE_DIR; print('::set-output name=dir::' + USER_CACHE_DIR)"
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ${{ steps.pip-cache.outputs.dir }}
     key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -362,7 +366,7 @@ Locations:
 
 ### Simple example
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: ~/.local/share/renv
     key: ${{ runner.os }}-renv-${{ hashFiles('**/renv.lock') }}
@@ -375,7 +379,7 @@ Replace `~/.local/share/renv` with the correct `path` if not using Ubuntu.
 ### Multiple OS's in a workflow
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'Linux')
   with:
     path: ~/.local/share/renv
@@ -383,7 +387,7 @@ Replace `~/.local/share/renv` with the correct `path` if not using Ubuntu.
     restore-keys: |
       ${{ runner.os }}-renv-
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'macOS')
   with:
     path: ~/Library/Application Support/renv
@@ -391,7 +395,7 @@ Replace `~/.local/share/renv` with the correct `path` if not using Ubuntu.
     restore-keys: |
       ${{ runner.os }}-renv-
 
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   if: startsWith(runner.os, 'Windows')
   with:
     path: ~\AppData\Local\renv
@@ -403,7 +407,7 @@ Replace `~/.local/share/renv` with the correct `path` if not using Ubuntu.
 ## Ruby - Bundler
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: vendor/bundle
     key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
@@ -422,42 +426,32 @@ When dependencies are installed later in the workflow, we must specify the same
 ## Rust - Cargo
 
 ```yaml
-- name: Cache cargo registry
+- name: Cache cargo
-  uses: actions/cache@v1
+  uses: actions/cache@v2
   with:
-    path: ~/.cargo/registry
+    path: |
-    key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+      ~/.cargo/registry
-- name: Cache cargo index
+      ~/.cargo/git
-  uses: actions/cache@v1
+      target
-  with:
+    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-    path: ~/.cargo/git
-    key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
-- name: Cache cargo build
-  uses: actions/cache@v1
-  with:
-    path: target
-    key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
 ```
 
 ## Scala - SBT
 
 ```yaml
-- name: Cache SBT ivy cache
-  uses: actions/cache@v1
-  with:
-    path: ~/.ivy2/cache
-    key: ${{ runner.os }}-sbt-ivy-cache-${{ hashFiles('**/build.sbt') }}
 - name: Cache SBT
-  uses: actions/cache@v1
+  uses: actions/cache@v2
   with:
-    path: ~/.sbt
+    path: | 
+      ~/.ivy2/cache
+      ~/.sbt
     key: ${{ runner.os }}-sbt-${{ hashFiles('**/build.sbt') }}
 ```
 
 ## Swift, Objective-C - Carthage
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: Carthage
     key: ${{ runner.os }}-carthage-${{ hashFiles('**/Cartfile.resolved') }}
@@ -468,7 +462,7 @@ When dependencies are installed later in the workflow, we must specify the same
 ## Swift, Objective-C - CocoaPods
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: Pods
     key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
@@ -479,7 +473,7 @@ When dependencies are installed later in the workflow, we must specify the same
 ## Swift - Swift Package Manager
 
 ```yaml
-- uses: actions/cache@v1
+- uses: actions/cache@v2
   with:
     path: .build
     key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}