From 43c8cd8b3f02c5e9f4bd3dd602d04d8afa5c6b7b Mon Sep 17 00:00:00 2001 From: Alex Ball Date: Sun, 2 Mar 2025 21:54:48 -0500 Subject: [PATCH] Docs: Clarify that setting cache-keys overrides defaults (#11895) ## Summary The current wording on the [caching page](https://docs.astral.sh/uv/concepts/cache/#dynamic-metadata) makes it sounds like defining `cache-keys` in a project adds to the metadata considered when caching. However it actually replaces the metadata. So copying the example using the git commit results in only considering the git commit, not the pyproject.toml, which is likely not what is typically desired. --------- Co-authored-by: Charlie Marsh --- docs/concepts/cache.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index 5958cd626..3b84e31cf 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -32,16 +32,21 @@ By default, uv will _only_ rebuild and reinstall local directory dependencies (e the `pyproject.toml`, `setup.py`, or `setup.cfg` file in the directory root has changed. This is a heuristic and, in some cases, may lead to fewer re-installs than desired. -To incorporate other information into the cache key for a given package, you can add cache key -entries under `tool.uv.cache-keys`, which can include both file paths and Git commit hashes. +To incorporate additional information into the cache key for a given package, you can add cache key +entries under [`tool.uv.cache-keys`](https://docs.astral.sh/uv/reference/settings/#cache-keys), +which covers both file paths and Git commit hashes. Setting +[`tool.uv.cache-keys`](https://docs.astral.sh/uv/reference/settings/#cache-keys) will replace +defaults, so any necessary files (like `pyproject.toml`) should still be included in the +user-defined cache keys. -For example, if a project uses [`setuptools-scm`](https://pypi.org/project/setuptools-scm/), and -should be rebuilt whenever the commit hash changes, you can add the following to the project's -`pyproject.toml`: +For example, if a project specifies dependencies in `pyproject.toml` but uses +[`setuptools-scm`](https://pypi.org/project/setuptools-scm/) to manage its version, and should thus +be rebuilt whenever the commit hash or dependencies change, you can add the following to the +project's `pyproject.toml`: ```toml title="pyproject.toml" [tool.uv] -cache-keys = [{ git = { commit = true } }] +cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true } }] ``` If your dynamic metadata incorporates information from the set of Git tags, you can expand the cache @@ -49,7 +54,7 @@ key to include the tags: ```toml title="pyproject.toml" [tool.uv] -cache-keys = [{ git = { commit = true, tags = true } }] +cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }] ``` Similarly, if a project reads from a `requirements.txt` to populate its dependencies, you can add @@ -57,7 +62,7 @@ the following to the project's `pyproject.toml`: ```toml title="pyproject.toml" [tool.uv] -cache-keys = [{ file = "requirements.txt" }] +cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }] ``` Globs are supported, following the syntax of the @@ -80,7 +85,7 @@ project's `pyproject.toml` to invalidate the cache whenever the environment vari ```toml title="pyproject.toml" [tool.uv] -cache-keys = [{ env = "MY_ENV_VAR" }] +cache-keys = [{ file = "pyproject.toml" }, { env = "MY_ENV_VAR" }] ``` As an escape hatch, if a project uses `dynamic` metadata that isn't covered by `tool.uv.cache-keys`,