Merge 8f0a0b0eda into e9c40fbc2b

docs/advanced-usage.md

@@ -330,7 +330,8 @@ steps:
 
 ## Caching packages
 
-**Caching pipenv dependencies:**
+### Caching pipenv dependencies
+
 ```yaml
 steps:
 - uses: actions/checkout@v4
@@ -343,7 +344,8 @@ steps:
 - run: pipenv install
 ```
 
-**Caching poetry dependencies:**
+### Caching poetry dependencies
+
 ```yaml
 steps:
 - uses: actions/checkout@v4
@@ -358,7 +360,8 @@ steps:
 ```
 >**Note:** If the `setup-python` version does not match the version specified in `pyproject.toml` and the python version in `pyproject.toml` is less than the runner's python version, `poetry install` will default to using the runner's Python version.
 
-**Using a list of file paths to cache dependencies**
+### Using a list of file paths to cache dependencies
+
 ```yaml
 steps:
 - uses: actions/checkout@v4
@@ -373,7 +376,9 @@ steps:
   run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
 - run: pipenv install
 ```
-**Using wildcard patterns to cache dependencies**
+
+### Using wildcard patterns to cache dependencies
+
 ```yaml
 steps:
 - uses: actions/checkout@v4
@@ -385,7 +390,8 @@ steps:
 - run: pip install -r subdirectory/requirements-dev.txt
 ```
 
-**Using a list of wildcard patterns to cache dependencies**
+### Using a list of wildcard patterns to cache dependencies
+
 ```yaml
 steps:
 - uses: actions/checkout@v4
@@ -399,7 +405,7 @@ steps:
 - run: pip install -e . -r subdirectory/requirements-dev.txt
 ```
 
-**Caching projects that use setup.py:**
+### Caching projects that use setup.py (or pyproject.toml)
 
 ```yaml
 steps:
@@ -413,6 +419,42 @@ steps:
   # Or pip install -e '.[test]' to install test dependencies
 ```
 
+### Skipping cache saving
+
+For some scenarios, it may be useful to only save a given subset of dependencies,
+but restore more of them for other workflows. For instance, there may be a heavy
+`extras` dependency that you do not need your entire test matrix to download, but
+you want to download and test it separately without it being saved in the cache
+archive for all runs.
+
+To achieve this, you can use `cache-save: false` on the run that uses the heavy
+dependency.
+
+
+```yaml
+test:
+  steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v4
+    with:
+      python-version: '3.11'
+      cache: 'pip'
+      cache-dependency-path: pyproject.toml
+  - run: pip install -e .
+
+test-heavy-extra:
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v4
+        with:
+        python-version: '3.11'
+        cache: 'pip'
+        cache-dependency-path: pyproject.toml
+        cache-save: false
+    - run: pip install -e '.[heavy-extra]'
+```
+
+
 # Outputs and environment variables
 
 ## Outputs