From 12ef78f396bb5ebb548b2302f54c3d3911504e06 Mon Sep 17 00:00:00 2001
From: Sergey Dolin <dsame@github.com>
Date: Tue, 29 Aug 2023 19:44:05 +0200
Subject: [PATCH] Update README.md with more sample

---
 README.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 136 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6dafed1f9..b3423670a 100644
--- a/README.md
+++ b/README.md
@@ -171,11 +171,146 @@ steps:
   - uses: actions/setup-go@v4
     with:
       go-version: '1.17'
-      check-latest: true
       cache-dependency-path: subdir/go.sum
   - run: go run hello.go
   ```
 
+**Caching in multirepos**
+`cache-dependency-path` input assepts glob patterns and multi-line values:
+
+```yaml
+steps:
+  - uses: actions/checkout@v3
+  - uses: actions/setup-go@v4
+    with:
+      go-version: '1.17'
+      cache-dependency-path: **/go.sum
+  - run: go run hello.go
+  ```
+
+```yaml
+steps:
+  - uses: actions/checkout@v3
+  - uses: actions/setup-go@v4
+    with:
+      go-version: '1.17'
+      cache-dependency-path: |
+        subdir1/go.sum
+        subdir2/go.mod
+  - run: go run hello.go
+  ```
+
+## Multi-target builds
+`cache-dependency-path` input used to generate unuque cache key and it is not limited to only
+dependencies files. The common case is to add a file containing the extr info about the specific
+build, for example build target.
+
+```yaml
+env:
+  GOOS: ...
+  GOARCH: ...
+
+steps:
+  - run: echo "$GOOS $GOARCH"> /tmp/env
+
+  - uses: actions/setup-go@v4
+    with:
+      go-version: '1.17'
+      cache-dependency-path: go.sum /tmp/env
+  - run: go run hello.go    
+```
+
+## Invalidate cache when source code changes
+Besides the dependencise the action caches the build outputs 
+([GOCACHE](https://pkg.go.dev/cmd/go#hdr-Build_and_test_caching) directory) but by default this
+cache is not update in order to avoid unpredictable and frequent cache invaldation. Nevertheless
+including the source code files into `cache-dependency-path` input.
+
+```yaml
+- uses: actions/setup-go@v4
+  with:
+    go-version: '1.17'
+    cache-dependency-path: go.sum **/*.go
+- run: go run hello.go
+```
+
+But more practically to manage the cache with the text file manually updated according to the amount
+of changes made in the repo.
+
+```yaml
+- uses: actions/setup-go@v4
+  with:
+    go-version: '1.17'
+    cache-dependency-path: go.sum cache-version.txt
+- run: go run hello.go
+```
+
+## Caching with actions/cache
+The caching capabilities of the action are limited for the simplest builds and can be ineffective in the real world
+use cases. If the build requires fine-grained turning the built-in caching should be disabled and
+[actions/cache](https://github.com/actions/cache) should be used.
+
+Here the sample `actions/cache` configuration with the extending options allowing 
+ - configuring paths to cache
+ - have different caches for rare changes dependencies and more often changed intermediate build files
+ - use `restore-key` input to restore the previous cache even if the current key cache has changed
+ - have different caches intermediate build files of different architectures
+ - have custom cache key for parallel builds
+
+```yaml
+build:
+  env:
+   GOOS: ...
+   GOARCH: ...
+
+  steps:
+  - uses: actions/setup-go@v4
+    with:
+      go-version: "1.17"
+      cache: false
+
+  - name: Get Go cached paths
+    run: |
+      echo "cache=$(go env GOCACHE)" >> $GITHUB_ENV
+      echo "modcache=$(go env GOMODCACHE)" >> $GITHUB_ENV
+
+  - name: Set up dependencies cache
+    uses: actions/cache@v3
+    with:
+      path: |
+        ${{ env.cache }}
+      key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }}
+      restore-keys: |
+        setup-go-deps-${{ runner.os }}-go-
+
+  - name:
+    run: echo "$GOOS $GOARCH"> /tmp/env
+
+  - name: Set up intermediate built files cache
+    uses: actions/cache@v3
+    with:
+      path: |
+        ${{ env.modcache }}
+      key: setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go-${{ hashFiles('**/*.go /tmp/env') }}
+      restore-keys: |
+        setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}
+
+```
+
+## Restore-only caches
+If there are several builds on the same repo it might make sense to create a cache in one build and use it in the
+others. The action [actions/cache/restore](https://github.com/marketplace/actions/cache-restore)
+should be used in this case.
+
+## Generate different caches
+This advanced use case assumes manual definition of cache key and requires the use of
+[actions/cache](https://github.com/actions/cache/blob/main/examples.md#go---modules)
+
+## Parallel builds
+To avoid race conditions during the parallel builds they should either
+[generate their own caches](#generate-different-caches), or create the cache
+for only one build and [restore](#restore-only-caches) that cache in the other builds.
+
 ## Getting go version from the go.mod file
 
 The `go-version-file` input accepts a path to a `go.mod` file or a `go.work` file that contains the version of Go to be