astral-sh/uv

uv-git

crates/uv-git/ adds Git source distributions to uv. When a requirement points at a Git URL (git+https://github.com/example/pkg.git@main), this crate fetches, checks out, and resolves the right revision so the build frontend can build a wheel from it.

The implementation is adapted from Cargo's git source support (the README's Acknowledgements section calls this out).

Purpose

Resolve git revisions: branches, tags, commits, and short SHAs.
Cache repositories on disk to avoid re-cloning.
Apply rate-limiting to GitHub-style hosts so a single resolution doesn't accidentally DDoS an index.
Parse credentials from URLs and pass them to git.

Directory layout

crates/uv-git/src/
├── lib.rs           # Re-exports
├── credentials.rs   # GitCredential parsing
├── git.rs           # 31k chars: low-level git operations (clone, fetch, checkout)
├── rate_limit.rs    # Per-host rate limiter for GitHub-style APIs
├── resolver.rs      # GitResolver: cached resolution of revs to commits
└── source.rs        # GitSource: a single git URL + ref + state

Key abstractions

Type	Role
`GitResolver`	Caches resolutions of "URL + ref" → commit SHA so a single resolution doesn't re-resolve.
`GitSource`	A single git source: URL, requested ref, fetched commit.
`GitCredential`	Username/password (or token) for git over HTTPS.
`RateLimiter`	Per-host throttle to avoid hammering GitHub's git protocol.

How it works

flowchart LR
    requirement[git+https://...@v1.2] --> resolver[GitResolver]
    resolver -->|cache hit| resolved[Commit SHA]
    resolver -->|cache miss| ratelimiter[RateLimiter]
    ratelimiter --> git[Spawn `git ls-remote`]
    git --> resolved
    resolved --> source[GitSource::checkout]
    source --> cache[(~/.cache/uv/git-v0/...)]
    cache --> wheel[Build via uv-build-frontend]

GitResolver uses git itself (not libgit2) — it spawns the system git binary for clone, fetch, and ls-remote. The implementation copies Cargo's approach of separating the "shared clone" (the bare repo cached in git-vN/db/) from per-revision worktrees.

Integration points

uv-distribution is the consumer; it owns BuildableSource variants for git URLs.
uv-cache stores the bare repository and worktrees.
uv-auth provides Credentials. The credential helper integration also lets uv act as a git credential provider for nested git operations.

Entry points for modification

A new git host quirk — git.rs. The crate already special-cases GitHub for rate limiting; new hosts can be added the same way.
Tweaking caching — resolver.rs (revision cache) and git.rs (clone/fetch policy).

Key source files

File	Purpose
`crates/uv-git/src/git.rs`	Low-level git operations.
`crates/uv-git/src/resolver.rs`	Revision resolution cache.
`crates/uv-git/src/source.rs`	High-level `GitSource`.