Example for restore-only cache in documentation (actions#696)

* cache-restore-only example

* resolve conflicts

* example update

* format update

* format update

* update

Author: priyagupta108

README.md

@@ -316,6 +316,68 @@ steps:
 
 > **Note**: If caching fails, the action logs a warning but continues execution without interrupting your workflow.
 
+**Restore-Only Cache**
+
+```yaml
+# In some workflows, you may want to restore a cache without saving it. This can help reduce cache writes and storage usage in workflows that only need to read from cache
+jobs:
+    build:
+      runs-on: ${{ matrix.os }}
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest, windows-latest]
+      steps:
+        - uses: actions/checkout@v6
+        - name: Setup Go
+          id: setup-go
+          uses: actions/setup-go@v6
+          with:
+            go-version: '1.24.10'
+            cache: false
+        # Capture Go cache locations
+        - name: Set Go cache variables (Linux/macOS)
+          if: runner.os != 'Windows'
+          run: |
+            echo "GO_MOD_CACHE=$(go env GOMODCACHE)" >> $GITHUB_ENV
+            echo "GO_BUILD_CACHE=$(go env GOCACHE)" >> $GITHUB_ENV
+        - name: Set Go cache variables (Windows)
+          if: runner.os == 'Windows'
+          shell: pwsh
+          run: |
+            echo "GO_MOD_CACHE=$(go env GOMODCACHE)" | Out-File $env:GITHUB_ENV -Append
+            echo "GO_BUILD_CACHE=$(go env GOCACHE)"   | Out-File $env:GITHUB_ENV -Append
+        # Normalize runner.arch to lowercase to ensure consistent cache keys
+        - name: Normalize runner architecture (Linux/macOS)
+          if: runner.os != 'Windows'
+          shell: bash
+          run: echo "ARCH=$(echo '${{ runner.arch }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+        - name: Normalize runner architecture (Windows)
+          if: runner.os == 'Windows'
+          shell: pwsh
+          run: |
+            $arch = "${{ runner.arch }}".ToLower()
+            echo "ARCH=$arch" | Out-File $env:GITHUB_ENV -Append
+        - name: Set cache OS suffix for Linux
+          if: runner.os == 'Linux'
+          shell: bash
+          run: echo "CACHE_OS_SUFFIX=$ImageOS-" >> $GITHUB_ENV    
+        - name: Restore Go cache
+          id: go-cache
+          uses: actions/cache/restore@v5
+          with:
+            path: |
+              ${{ env.GO_MOD_CACHE }}
+              ${{ env.GO_BUILD_CACHE }}
+            key: setup-go-${{ runner.os }}-${{ env.ARCH }}-${{ env.CACHE_OS_SUFFIX }}go-${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('**/go.sum') }}
+        - name: Download modules
+          run: go mod download
+        - name: Build
+          run: go build ./...
+```
+> 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/actions/cache/tree/main/restore#only-restore-cache)
+should be used in this case.
+
 ### Matrix Testing
 
 Test across multiple Go versions: