Split up documentation (#632)

Closes: #558

docs/caching.md

@@ -0,0 +1,189 @@
+# Caching
+
+This document covers all caching-related configuration options for setup-uv.
+
+## Enable caching
+
+> [!NOTE]
+> The cache is pruned before it is uploaded to the GitHub Actions cache. This can lead to
+> a small or empty cache. See [Disable cache pruning](#disable-cache-pruning) for more details.
+
+If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
+the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
+Caching is enabled by default on GitHub-hosted runners.
+
+> [!TIP]
+>
+> On self-hosted runners this is usually not needed since the cache generated by uv on the runner's
+> filesystem is not removed after a run. For more details see [Local cache path](#local-cache-path).
+
+You can optionally define a custom cache key suffix.
+
+```yaml
+- name: Enable caching and define a custom cache key suffix
+  id: setup-uv
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-suffix: "optional-suffix"
+```
+
+When the cache was successfully restored, the output `cache-hit` will be set to `true` and you can
+use it in subsequent steps. For example, to use the cache in the above case:
+
+```yaml
+- name: Do something if the cache was restored
+  if: steps.setup-uv.outputs.cache-hit == 'true'
+  run: echo "Cache was restored"
+```
+
+## Cache dependency glob
+
+If you want to control when the GitHub Actions cache is invalidated, specify a glob pattern with the
+`cache-dependency-glob` input. The GitHub Actions cache will be invalidated if any file matching the glob pattern
+changes. If you use relative paths, they are relative to the repository root.
+
+> [!NOTE]
+>
+> You can look up supported patterns [here](https://github.com/actions/toolkit/tree/main/packages/glob#patterns)
+>
+> The default is
+> ```yaml
+> cache-dependency-glob: |
+>   **/*requirements*.txt
+>   **/*requirements*.in
+>   **/*constraints*.txt
+>   **/*constraints*.in
+>   **/pyproject.toml
+>   **/uv.lock
+>   **/*.py.lock
+> ```
+
+```yaml
+- name: Define a cache dependency glob
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-dependency-glob: "**/pyproject.toml"
+```
+
+```yaml
+- name: Define a list of cache dependency globs
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-dependency-glob: |
+      **/requirements*.txt
+      **/pyproject.toml
+```
+
+```yaml
+- name: Define an absolute cache dependency glob
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
+```
+
+```yaml
+- name: Never invalidate the cache
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-dependency-glob: ""
+```
+
+## Restore cache
+
+Restoring an existing cache can be enabled or disabled with the `restore-cache` input.
+By default, the cache will be restored.
+
+```yaml
+- name: Don't restore an existing cache
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    restore-cache: false
+```
+
+## Save cache
+
+You can also disable saving the cache after the run with the `save-cache` input.
+This can be useful to save cache storage when you know you will not use the cache of the run again.
+By default, the cache will be saved.
+
+```yaml
+- name: Don't save the cache after the run
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    save-cache: false
+```
+
+## Local cache path
+
+If caching is enabled, this action controls where uv stores its cache on the runner's filesystem
+by setting `UV_CACHE_DIR`.
+
+It defaults to `setup-uv-cache` in the `TMP` dir, `D:\a\_temp\setup-uv-cache` on Windows and
+`/tmp/setup-uv-cache` on Linux/macOS. You can change the default by specifying the path with the
+`cache-local-path` input.
+
+> [!NOTE]
+> If the environment variable `UV_CACHE_DIR` is already set this action will not override it.
+> If you configured [cache-dir](https://docs.astral.sh/uv/reference/settings/#cache-dir) in your
+> config file then it is also respected and this action will not set `UV_CACHE_DIR`.
+
+```yaml
+- name: Define a custom uv cache path
+  uses: astral-sh/setup-uv@v6
+  with:
+    cache-local-path: "/path/to/cache"
+```
+
+## Disable cache pruning
+
+By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any
+wheels that were built from source. On GitHub-hosted runners, it's typically faster to omit those
+pre-built wheels from the cache (and instead re-download them from the registry on each run).
+However, on self-hosted or local runners, preserving the cache may be more efficient. See
+the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration) for
+more information.
+
+If you want to persist the entire cache across runs, disable cache pruning with the `prune-cache`
+input.
+
+```yaml
+- name: Don't prune the cache before saving it
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    prune-cache: false
+```
+
+## Cache Python installs
+
+By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
+for the same reason that the dependency cache is pruned.
+If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.
+
+```yaml
+- name: Cache Python installs
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    cache-python: true
+```
+
+## Ignore nothing to cache
+
+By default, the action will fail if caching is enabled but there is nothing to upload (the uv cache directory does not exist).
+If you want to ignore this, set the `ignore-nothing-to-cache` input to `true`.
+
+```yaml
+- name: Ignore nothing to cache
+  uses: astral-sh/setup-uv@v6
+  with:
+    enable-cache: true
+    ignore-nothing-to-cache: true
+```