pioduino/uv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Docs: Clarify that setting cache-keys overrides defaults (#11895)

Browse Source 
## 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 <charlie.r.marsh@gmail.com>
This commit is contained in:
Alex Ball
2025-03-02 21:54:48 -05:00
committed by GitHub
parent 663ae63f2e
commit 43c8cd8b3f
1 changed files with 14 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/concepts/cache.md
+14 -9
View File
@@ -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`,