Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[Download] Scope the fix to resolve_revision: drop _commit_hash_for
Download helpers trust the passed `ResolvedRevision` again (`revision.resolved`
as before). The only behavior change is in `HfApi.resolve_revision`: a revision
resolved for another repo is resolved again for the requested one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
  • Loading branch information
Wauplin and claude committed Aug 28, 2026
commit 108db21d85923ec7e0c6186be85581352f1eecfa
7 changes: 4 additions & 3 deletions docs/source/en/guides/manage-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,12 +238,13 @@ Download helpers ([`hf_hub_download`], [`snapshot_download`], [`get_cached_repo_

The `revision` -> `commit hash` mapping is also written to the `refs/` folder of the cache (see [Refs](#refs)). This means that if the Hub cannot be reached later on (offline mode, connection error, timeout, Hub downtime), [`HfApi.resolve_revision`] transparently falls back to the cached value. If nothing is cached either, a [`~errors.RevisionResolutionError`] is raised.

A commit hash only means something for the repo it was resolved against, so a [`ResolvedRevision`] remembers that repo. Passing it to another one (a base model, an adapter, a component living in its own repo, ...) is safe: the revision initially requested is used instead, and resolved again if needed.
A commit hash only means something for the repo it was resolved against, and download helpers use it as is. So a [`ResolvedRevision`] must only be passed to the repo it was resolved for. If a library also downloads from another repo (a base model, an adapter, a component living in its own repo, ...), it needs a revision resolved for that repo. Just pass the [`ResolvedRevision`] back to [`HfApi.resolve_revision`]: it remembers which repo it belongs to and resolves the revision initially requested (`"main"` here) again for the new repo.

```py
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=revision) # downloads "main"
>>> resolve_revision("openai-community/gpt2-medium", revision=revision).resolved # resolves "main" again
>>> other_revision = resolve_revision("openai-community/gpt2-medium", revision=revision) # resolves "main" again
>>> other_revision.resolved
'6dcaa7a952f72f9298047fd5137cd6e4f05f41da'
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=other_revision)
```

## Chunk-based caching (Xet)
Expand Down
13 changes: 2 additions & 11 deletions src/huggingface_hub/_revision.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ class ResolvedRevision(str):
in the local cache (`refs/` folder).

A commit hash only means something for the repo it was resolved against, so an instance also remembers that
repo. Passing it to another repo is not an error: the initially requested revision is used instead, and
resolved again if needed.
repo. Re-resolving it for another repo is not an error: the revision initially requested is resolved again
(see [`HfApi.resolve_revision`]).

Attributes:
initial (`str` or `None`):
Expand Down Expand Up @@ -60,12 +60,3 @@ def __reduce__(self):

def __repr__(self) -> str:
return f"ResolvedRevision(initial={self.initial!r}, resolved={self.resolved!r})"

def _commit_hash_for(self, repo_id: str, repo_type: str | None = None) -> str | None:
"""The commit hash to use for this repo, or `None` if the revision was resolved against another one."""
if self._repo_id is None or (self._repo_id, self._repo_type) == (
repo_id,
repo_type or constants.REPO_TYPE_MODEL,
):
return self.resolved
return None
43 changes: 21 additions & 22 deletions src/huggingface_hub/_snapshot_download.py
Original file line number Diff line number Diff line change
Expand Up @@ -250,16 +250,15 @@ def snapshot_download(
token=token,
)

# The revision already pins a commit if:
# - it's a `ResolvedRevision` resolved for this repo (see [`HfApi.resolve_revision`])
# The revision is already a commit hash if:
# - it's a `ResolvedRevision` (already resolved, see [`HfApi.resolve_revision`])
# - it's a commit hash, which is immutable
# => in both cases, there is nothing to resolve and the `repo_info` call can be skipped.
pinned_commit_hash: str | None = None
commit_hash: str | None = None
if isinstance(revision, ResolvedRevision):
pinned_commit_hash = revision._commit_hash_for(repo_id, repo_type)
commit_hash = revision.resolved
elif REGEX_COMMIT_HASH.match(revision):
pinned_commit_hash = revision
commit_hash: str | None = pinned_commit_hash
commit_hash = revision

api_call_error: Exception | None = None
if commit_hash is None and not local_files_only:
Expand Down Expand Up @@ -412,8 +411,8 @@ def snapshot_download(
snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash)
# if passed revision is not identical to commit_hash
# then revision has to be a branch name or tag name.
# In that case store a ref, unless the revision came pinned: [`HfApi.resolve_revision`] already stored it.
if pinned_commit_hash is None and revision != commit_hash:
# In that case store a ref (except if ResolvedRevision, in which case it's already done).
if not isinstance(revision, ResolvedRevision) and revision != commit_hash:
ref_path = os.path.join(storage_folder, "refs", revision)
try:
os.makedirs(os.path.dirname(ref_path), exist_ok=True)
Expand Down Expand Up @@ -652,20 +651,20 @@ def get_cached_repo_tree(

# The tree cache is keyed by commit hash. Resolve the revision to a commit hash: either it already is one,
# or it's a branch/tag name recorded in `refs/` by a previous download.
commit_hash = revision._commit_hash_for(repo_id, repo_type) if isinstance(revision, ResolvedRevision) else None
if commit_hash is None:
if REGEX_COMMIT_HASH.match(revision):
commit_hash = revision
else:
ref_path = os.path.join(storage_folder, "refs", revision)
if not os.path.isfile(ref_path):
raise CachedRepoTreeNotFoundError(
f"No cached tree listing found for '{repo_id}' (revision '{revision}', repo_type '{repo_type}'): "
f"the revision is not a commit hash and no matching ref is cached in '{storage_folder}'. "
"Download the repo (e.g. with `snapshot_download`) to populate the cache first."
)
with open(ref_path) as f:
commit_hash = f.read()
if isinstance(revision, ResolvedRevision):
commit_hash = revision.resolved
elif REGEX_COMMIT_HASH.match(revision):
commit_hash = revision
else:
ref_path = os.path.join(storage_folder, "refs", revision)
if not os.path.isfile(ref_path):
raise CachedRepoTreeNotFoundError(
f"No cached tree listing found for '{repo_id}' (revision '{revision}', repo_type '{repo_type}'): "
f"the revision is not a commit hash and no matching ref is cached in '{storage_folder}'. "
"Download the repo (e.g. with `snapshot_download`) to populate the cache first."
)
with open(ref_path) as f:
commit_hash = f.read()

tree_entries = read_tree_cache(tree_cache_folder, commit_hash)
if tree_entries is None:
Expand Down
3 changes: 1 addition & 2 deletions src/huggingface_hub/file_download.py
Original file line number Diff line number Diff line change
Expand Up @@ -972,8 +972,7 @@ def hf_hub_download(
elif isinstance(revision, ResolvedRevision):
# Revision has already been resolved to a commit hash (see [`HfApi.resolve_revision`]) => use it directly.
# This pins the download to an immutable commit and lets us skip network calls when it's already cached.
# A revision resolved for another repo does not apply here => fall back to the revision it requested.
revision = revision._commit_hash_for(repo_id, repo_type) or str(revision)
revision = revision.resolved

if cache_dir is None:
cache_dir = constants.HF_HUB_CACHE
Expand Down
9 changes: 6 additions & 3 deletions src/huggingface_hub/hf_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -3729,15 +3729,18 @@ def resolve_revision(
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)
```
"""
if repo_type is None:
repo_type = constants.REPO_TYPE_MODEL

if isinstance(revision, ResolvedRevision):
if revision._commit_hash_for(repo_id, repo_type) is not None:
# A commit hash means nothing outside of the repo it was resolved for. `_repo_id=None` means the repo is
# unknown (instance built by hand), in which case it is assumed to fit any repo.
if revision._repo_id is None or (revision._repo_id, revision._repo_type) == (repo_id, repo_type):
return revision # already resolved for this repo => nothing to do
revision = revision.initial # resolved for another repo => resolve what was initially requested
if revision is not None and REGEX_COMMIT_HASH.match(revision):
return ResolvedRevision(resolved=revision, initial=revision, repo_id=repo_id, repo_type=repo_type)

if repo_type is None:
repo_type = constants.REPO_TYPE_MODEL
if cache_dir is None:
cache_dir = constants.HF_HUB_CACHE
storage_folder = str(
Expand Down
24 changes: 7 additions & 17 deletions tests/test_snapshot_download.py
Original file line number Diff line number Diff line change
Expand Up @@ -370,19 +370,9 @@ def test_revision_str_is_picklable():
assert restored == "refs/pr/4"
assert restored.initial == "refs/pr/4"
assert restored.resolved == COMMIT_HASH
assert restored._commit_hash_for("user/repo", "dataset") == COMMIT_HASH


def test_revision_str_commit_hash_for():
"""The commit hash only applies to the repo the revision was resolved against."""
revision = ResolvedRevision(resolved=COMMIT_HASH, repo_id="user/repo")
assert revision._commit_hash_for("user/repo") == COMMIT_HASH
assert revision._commit_hash_for("user/repo", "model") == COMMIT_HASH
assert revision._commit_hash_for("user/repo", "dataset") is None
assert revision._commit_hash_for("user/other-repo") is None

# Built by hand, without a repo => assumed to fit any repo
assert ResolvedRevision(resolved=COMMIT_HASH)._commit_hash_for("user/repo") == COMMIT_HASH
# the repo it was resolved for survives as well, otherwise it would be resolved again for that same repo
assert restored._repo_id == "user/repo"
assert restored._repo_type == "dataset"


class TestResolveRevision:
Expand Down Expand Up @@ -431,10 +421,10 @@ def test_resolve_revision_for_another_repo(self, api: HfApi, repo_factory, tmp_p
with pytest.raises(RepositoryNotFoundError):
api.resolve_revision(self.repo_id, repo_type="dataset", revision=revision, cache_dir=tmp_path)

# Downloads target the requested revision of that repo, not the commit hash of the other one
path = hf_hub_download(other_repo_id, "dummy_file.txt", revision=revision, cache_dir=tmp_path)
assert path.endswith(os.path.join(other_commit_hash, "dummy_file.txt"))
assert snapshot_download(other_repo_id, revision=revision, cache_dir=tmp_path).endswith(other_commit_hash)
# Built by hand, without a repo => trusted for any repo
by_hand = ResolvedRevision(resolved=self.commit_hash)
with offline():
assert api.resolve_revision(other_repo_id, revision=by_hand, cache_dir=tmp_path) is by_hand

def test_resolve_revision_not_cached(self, api: HfApi, tmp_path: Path):
with offline():
Expand Down
Loading