uv Moves Its Git Checkout Marker Outside Repository Content

Quick Answer

uv moves the marker for a completed Git checkout beside the checkout directory. A repository’s own .ok file can then coexist with uv’s readiness tracking.

In Plain English

Tools sometimes create a tiny file to record that a larger operation finished successfully. That file belongs to the tool’s bookkeeping. Putting it inside downloaded source gives the repository a chance to use the same name for an unrelated file.

Code Evidence

The Git checkout code switches from a .ok file inside the checkout to a neighboring path with an ok extension. It invalidates that marker before replacing a checkout and creates it after preparation succeeds. The Git cache bucket also advances to git-v1. Regression coverage checks that repository content named .ok survives and that a missing external marker forces preparation again.

Why It Matters

The design lesson is about ownership of state: downloaded content and the downloader’s control files should have separate locations. For teams caching Git dependencies, this makes readiness a property recorded by uv rather than a filename supplied by the project. It does not make arbitrary downloaded code trustworthy.

Two Owners Need Two Locations

A repository controls its checked-out files, including names that appear unusual to a person browsing the tree. A package tool controls its cache bookkeeping. Using the same path for both creates ambiguity: the presence of a file can mean either that the repository contains it or that the tool has finished preparing the checkout. Moving the marker outside the content directory removes that specific overlap.

The change is more than choosing a less common filename. A different hidden filename inside the repository could still collide with legitimate repository content. The neighboring marker gives uv a separate location for its own state. The reviewed patch uses an ok extension on that neighboring path and advances the Git cache bucket to git-v1, making the new layout explicit in the cache organization.

Readiness Has a Lifecycle

A completion marker is meaningful only when its creation and invalidation agree with the operation it describes. The code removes the marker before replacing the checkout and creates it after preparation succeeds. That ordering expresses the intended contract: a previous success must not continue to advertise readiness while the content is being replaced.

This is why the regression for a missing external marker matters alongside the repository .ok case. Preserving a source file proves that the new location avoids one collision. Preparing again when the external marker is absent tests the other half of the design: uv must use its own completion evidence rather than accept the repository's content as a substitute. Both observations are needed to understand the change.

A Cache Reuse Scenario

Imagine a project installing a Git dependency whose repository legitimately includes a file called .ok. The file may be an application fixture or simply part of that project's chosen structure. A cache mechanism should preserve it as source content without giving it control over whether preparation has finished. Under the revised arrangement, the repository file and uv's neighboring completion marker can coexist.

Now consider a checkout directory left without that external marker. The reviewed regression expects preparation to occur again, even if the repository's .ok file is present. This illustrative sequence shows the distinction between content existence and completed preparation. It does not prove resilience against every interrupted operation, filesystem failure, or concurrent process; those would require evidence beyond the assertions discussed here.

Verify the Upgrade with Cache State Visible

A focused project check should identify the uv version and the Git dependency revision before comparing behavior. In a disposable cache, install a small repository containing a known .ok file and confirm that the installed or checked-out source preserves its expected contents. Then inspect the tool's marker location according to the new layout. Avoid using a shared production cache for experiments that deliberately remove bookkeeping files.

If testing the absent-marker behavior, retain enough information to distinguish a fresh preparation from a simple reuse. The upstream test supplies a concrete regression expectation, but a project-level validation still needs an observable result in its own environment. Keep the repository revision unchanged so that a source update does not explain the repeated work instead.

The cache-bucket change also deserves attention when measuring an upgrade. A first run with a new layout may need to warm cache state that an older version already had. Compare that run separately from subsequent reuse and record the cache conditions. Otherwise, a one-time migration cost can be mistaken for a continuing performance regression, or a warm-cache run can hide the cost users will see on first use.

A Deliberately Limited Trust Claim

The marker tells uv about preparation state; it does not certify the safety or correctness of repository code. Separating control files from content is a useful ownership boundary, but it is not a substitute for choosing and reviewing dependencies. The source-backed conclusion is that a repository .ok file no longer occupies the tool's readiness path, and that the tested missing-marker case triggers preparation again.

Scope and Limitations

We reviewed the marker lifecycle and regression assertions. We did not run an adversarial checkout or audit the complete Git dependency implementation.

Sources

• Source diff and tests: PR #21891
• uv 0.12.19 release notes