From 581312be20743c5ab2ac8552538146f139661810 Mon Sep 17 00:00:00 2001 From: Aiqiao Yan Date: Tue, 26 May 2020 12:45:38 -0400 Subject: [PATCH] Update readme and examples to use v2 --- README.md | 67 +++++++++++++++++++++++++--- examples.md | 124 +++++++++++++++++++++++++--------------------------- 2 files changed, 120 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 6e93a87..3433950 100644 --- a/README.md +++ b/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 diff --git a/examples.md b/examples.md index ce31929..3666cd8 100644 --- a/examples.md +++ b/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 - name: Cache ~/.cabal/packages +- uses: actions/cache@v2 + name: Cache ~/.cabal/packages, ~/.cabal/store and dist-newstyle with: - path: ~/.cabal/packages - key: ${{ runner.os }}-${{ matrix.ghc }}-cabal-packages -- uses: actions/cache@v1 - name: Cache ~/.cabal/store - with: - 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 + path: | + ~/.cabal/packages + ~/.cabal/store + dist-newstyle + key: ${{ runner.os }}-${{ matrix.ghc }} ``` ## 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 - uses: actions/cache@v1 +- name: Cache cargo + uses: actions/cache@v2 with: - path: ~/.cargo/registry - key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }} -- name: Cache cargo index - uses: actions/cache@v1 - with: - 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') }} + path: | + ~/.cargo/registry + ~/.cargo/git + target + key: ${{ runner.os }}-cargo-${{ 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') }}