Git 2.51: Cruft-aware MIDX, path-walk packing, portable stashes on Windows

The Git project has shipped version 2.51, a substantial maintenance-and-performance release that packs several storage-layer improvements aimed squarely at large repositories and monorepos, a new on-disk stash interchange format that finally makes stashes portable between machines, and foundational work that edges Git closer to the long-planned Git 3.0 changes (reftable, SHA‑256). For Windows developers and administrators, the release also includes fixes and defaults that reduce long-standing cross-platform friction (notably reftable’s benefits for case-insensitive filesystems). This piece unpacks the technical changes, explains concrete implications for Windows-based workflows and teams, and offers practical guidance for safely adopting the new features in production environments.

Background / Overview​

Git stores repository content as objects (blobs, trees, commits, tags) either as loose objects on disk or grouped into packfiles for compact storage and transfer. Packfiles reduce disk usage and accelerate network transfers but introduce another dimension of overhead: when a repository contains many packfiles, object lookups can become slow because the system must consult several pack indexes. The multi-pack index (MIDX) concept addresses this by providing a single index that covers objects across many packfiles, reducing lookup complexity and enabling faster reads.
At the same time, Git maintains unreachable objects in separate cruft packs to avoid bloating primary packfiles; unreachable objects are often left there to preserve older or transient history until garbage collection removes them. Until now, that separation caused implementation and performance tensions between the MIDX and reachability bitmaps used to speed up reachability queries. Git 2.51 introduces targeted changes to how packs are created and indexed to resolve those tensions, and it brings several other features that improve packing efficiency, stash portability, and future-proofing around the Git 3.0 direction.

---

What’s new in Git 2.51 — high-level bullets​

• Cruft-aware MIDX repacking: a new repacking behavior and a configuration flag that allow cruft packs to be stored outside the MIDX while preserving correctness of reachability bitmaps.
• Path-walk packing: a new object-collection method that emits objects grouped by path, creating smaller packs in many workloads and improving delta selection.
• Stash interchange format: stash entries can now be exported/imported as a chain of commits, enabling stashes to be pushed and fetched like ordinary refs.
• Reftable / Git 3.0 groundwork: further moves toward making reftable the default reference backend and prepping SHA‑256 as the future default object hash.
• Stability and UX: git switch and git restore are no longer experimental; git-whatchanged is being deprecated for removal in the Git 3.0 era.
• Various packing, bitmap and multi-pack-index refinements to improve speed, disk usage and maintenance on large repositories.

Each of these items has operational consequences; the sections below walk through why they matter and how to use them safely.

---

Deep dive: multi-pack indexes, cruft packs and repacking​

How packs, MIDX and bitmaps interact​

To understand the 2.51 change, it helps to re-state three concepts:

• A packfile stores many objects together; each pack has an index file (.idx) mapping object IDs to offsets.
• A MIDX (multi-pack index) is a single index that references objects across multiple packfiles, enabling lookups without scanning every .idx.
• A reachability bitmap is a compact per-commit (or per-selected-commit) bitset stating which MIDX-positioned objects are reachable from that commit; bitmaps make reachability queries extremely fast.

Historically, unreachable objects were shoved into cruft packs, intentionally left out of the MIDX to keep the multi-pack index smaller. However, a corner case emerged: if an object was only present in a cruft pack (so not in the MIDX) but later became reachable via a commit that had a reachability bitmap, there was no bit position for that object inside the MIDX — the bitmap couldn’t refer to the object — making the bitmap generation or correctness impossible.

What changed in 2.51​

Git 2.51 alters how repacking decides which objects belong to the set of non-cruft packs. When creating new packs, Git will now duplicate objects (and their ancestors) into the non-cruft set if the object’s only other copy is in a cruft pack. Repeated application of this rule ensures the set of non-cruft packs is closed under reachability: no object in the non-cruft set references an object that lives exclusively in cruft. The practical result is that bitmaps can be written reliably for the MIDX without having to include cruft packs inside the MIDX itself.
A new configuration option — introduced with 2.51 — allows repositories to opt into behavior that keeps cruft packs out of the MIDX (reducing MIDX size) while ensuring bitmaps remain writable and correct. In large-scale testing, that approach can substantially reduce MIDX size and write time, at modest read-performance benefit in some scenarios.

Real-world impact and operational guidance​

• Disk and read-performance tradeoffs: keeping cruft packs out of the MIDX reduces the MIDX footprint (fewer entries to index and store) and can speed up MIDX build time. On very large repositories, teams have reported MIDX shrinkage and measurable write-time reductions. However, writing packs that duplicate objects increases temporary disk usage during repack operations — plan for additional free space before you repack.
• When to enable: consider enabling the feature if you operate very large repositories with many packfiles and write MIDXes regularly (server-side hosting, monorepos). For normal desktop workflows, the default behavior will remain safe and the benefits are less pronounced.
• How to try: perform experiments on a replica or clone of the repository. Run git repack with the MIDX-related options in a maintenance window and monitor disk, CPU and repository health. Back up the repository (or test on a mirror) before enabling aggressive repacking strategies.

---

Path-walk packing: finding better delta bases by grouping by path​

Background: name-hash and delta selection​

Git’s delta compression chooses candidate bases for delta encoding by sorting objects according to a hash of their path and scanning a sliding window to identify nearby candidates. That approach was modernized in earlier versions (name-hash v2) to consider more of the path hierarchy instead of disproportionally privileging the last 16 characters of the path. Name-hash v2 shrank packs in some scenarios.

Path-walk in 2.51: what it does​

Git 2.51 introduces a new path-walk collection method during repacking. Instead of emitting objects in revision order and relying on name-hash sorting heuristics, path-walk emits all objects for a given path at once. This exposes more natural clusters of related blobs (files that actually live at the same path across history), allowing delta selection to find better bases and yielding smaller packs in many repositories — often smaller than even the improved name-hash v2 results.
Path-walk is available as a pack-objects/repack option (exposed as a repack flag), so you can test it with standard maintenance commands. Its timings are competitive with existing traversal modes, but CPU and memory behavior depends on repository layout and the configuration of window/depth parameters.

Practical usage and tips​

• Example repack invocation:
• Use a bare clone or maintenance mirror: git clone --mirror <repo-url>
• Run a repack with path-walk (safe test): git repack -a -d --path-walk
• If you plan to write a MIDX and bitmaps: git repack -a -d --path-walk -b -m
• Tune memory and threads: the repack options --threads, --window, --depth and --window-memory remain relevant with path-walk. For large repositories set --threads to a value matching your CPU and use --window-memory to cap memory usage.
• Expect different gains by repository type. Codebases with many repeated filenames or with large binary files in the same paths (for example, compiled artifacts) may see notable improvements. Repos with chaotic paths or less repeated history may not see material savings.
• Always test in a mirror; repacking can be I/O and CPU intensive and duplicates content while running.

---

Stash export/import — finally portable stashes​

Why this matters​

Historically, git stash stored the latest stash entry as a special ref (refs/stash) and older entries in the reflog. That design made stash entries difficult to migrate between machines or to store as a single ref that could be pushed. Developers who needed to move stashes between machines had to serialize entries manually — a clumsy, error-prone process.

What 2.51 changes​

Git 2.51 introduces an internal stash representation variant where stash entries are recorded as a chain of commits whose parent relationships include a pointer to the previous stash entry. The revamped representation changes stash entries from three-parent merge-like commits to entries that can include a previous-stash parent, resulting in stash commits that have four (or in some cases five) parents. Crucially, this makes the stash list behave like an ordinary commit log: you can export it to a ref and push or fetch it.
Two new git stash subcommands make this practical:

• git stash export --to-ref <ref> — writes the selected stashes as a linear sequence of commits to the specified ref (for example refs/stashes/my-stash).
• git stash import <commit> — imports the stash chain from the specified commit and appends its entries to the local stash list.

Typical workflow example:

• On Machine A:
• git stash export --to-ref refs/stashes/my-stash
• git push origin refs/stashes/my-stash
• On Machine B:
• git fetch origin '+refs/stashes/:refs/stashes/'
• git stash import refs/stashes/my-stash

This makes moving stashes between workstations, CI systems, or servers trivial and scriptable.

Caveats and guidance​

• Backwards compatibility: older Git versions will not understand the new stash-export ref semantics if they encounter the new stash commit shapes. When exporting and pushing stashes to a shared remote, ensure the remote and the machines that will fetch the ref are running Git versions that safely ignore unknown refs, or coordinate upgrades.
• Conflict semantics: imported stashes are appended to the local stash log. If your workflow relies on stash reflog entries being at particular positions, note the positions will change.
• Untracked and ignored files: stashing that included untracked/ignored data sometimes generates extra internal commits in the stash object graph; expect minor variance in parent-count across special cases. Test cross-machine transfers to ensure the content you expect is preserved.

---

Reftable and Git 3.0 preparation: Windows-relevant changes​

Git 2.51 continues work toward Git 3.0 by switching on or preparing several backend adjustments:

• Reftable improvements: reftable is being pushed as the new reference storage backend with several practical benefits for Windows:
• Reftable doesn’t encode refs as filesystem paths, so Windows’ case-insensitive filesystems no longer risk collisions when two ref names differ only by case. This removes an ancient source of cross-platform pain for teams that collaborate across macOS, Windows and Linux.
• Reftable’s performance characteristics (batched updates and auto-compaction) substantially reduce overhead when updating many refs; benchmarks show dramatic improvements in bulk-ref operations.
• SHA‑256 planning: the release continues to prepare for SHA‑256 as the default object hash in Git 3.0. This is a long migration that affects downstream tooling, signing, and any systems that assume SHA‑1 object IDs.

What Windows administrators should know​

• Reftable’s defaulting for new repositories removes some previously awkward Windows-specific limits. If you run hosting infrastructure, consider experimenting with new repositories under a reftable feature flag and measure reference-update workloads (large-scale CI pushes, tag floods).
• SHA‑256 migration is a big compatibility change. Tools that parse OIDs or hard-code SHA‑1 lengths must be updated; cross-platform teams should audit scripts, CI and backup software before migrating to SHA‑256 repositories.

---

UX changes, deprecations and small but important behavior changes​

• git switch and git restore are promoted from experimental to stable. These commands separate the historical responsibilities of git checkout into explicit workflows (switch for branch switching, restore for file restoration); they are now considered stable API for scripting and users.
• git-whatchanged is being deprecated and flagged for removal in Git 3.0. Scripts that still use it should move to git log --raw or other modern logging invocations.
• Pathspec and Bloom filter improvements: git log can now take multiple pathspec items and still sometimes leverage changed-path Bloom filters for faster path-scoped history queries. This helps interactive searches in very large repos.

---

Risks, gotchas and what to watch out for​

• Temporary disk pressure during repacks: operations that duplicate objects (to close non-cruft packs under reachability) increase temporary storage needs during repack runs. Always run repacks in a maintenance window and ensure sufficient free disk.
• Host-side timing and availability: repack operations are I/O heavy and may affect hosting performance. Schedule these during low-traffic windows on production servers.
• Compatibility of exported stash refs: pushing stash refs to remotes that might be accessed by older clients can cause confusion if users attempt to git stash import with older client versions. Use feature gates or coordinated upgrades.
• Tooling assumptions about OIDs and ref storage: scripts and third-party tools that assume SHA‑1 lengths, that parse refs by filesystem layout, or that rely on git-whatchanged will need updates during the Git 3.0 migration window.
• Bitmap / MIDX correctness caveats: while the new repack behavior fixes a correctness hole, edge cases still require care. Repositories that use alternates, promisor packs, or strange object layouts should test MIDX generation and bitmap writing in a sandbox first.

Where claims about percentage improvements are quoted from project testing, remember they are context-specific. Large platforms with monorepos and carefully tuned infrastructure reported noteworthy gains, but smaller repositories or different file layouts may see substantially different results.

---

Practical checklists — how to evaluate and adopt 2.51 safely​

For local developers and small teams​

• Upgrade your local Git client to 2.51 for improved stash portability and small packaging improvements.
• Use git stash export and git stash import to move stashes between machines only after confirming your collaborators are on compatible Git versions.
• For routine use, no immediate maintenance is required — defaults are conservative.

For enterprise hosts, monorepo operators, and Git administrators​

• Stage a test environment by mirroring repositories (git clone --mirror) into a maintenance host.
• Measure baseline metrics: MIDX sizes, repack times, fetch/pull latencies and memory/CPU use.
• Try repacking with the new options:
• git repack -a -d --path-walk (test pack size & time)
• Consider repack.MIDXMustContainCruft in a controlled trial and compare MIDX sizes and bitmap write success.
• Monitor disk consumption during repacks and ensure snapshots/backups exist.
• Validate clients and CI runners for SHA‑256 and reftable readiness if you plan to experiment with Git 3.0 feature flags.
• Inform and stage client upgrades to avoid ref parsing or stash compatibility issues.

---

Bottom line and recommendation​

Git 2.51 is a pragmatic release that sharpens Git’s storage and maintenance capabilities for large repositories while finally solving a long-standing usability gap for stash portability. The new path-walk packing algorithm and cruft-aware MIDX repacking demonstrate a steady engineering push toward better storage density and faster maintenance for massive codebases.
For Windows users, the reftable work reduces case-sensitivity pitfalls and improves ref-update performance in high-ref-count scenarios — welcome improvements for cross-platform teams. However, the more consequential changes (cruft handling, MIDX behavior and SHA‑256/reftable rollouts) are primarily impactful for server-side hosting and large-scale repository maintainers rather than casual desktop users.
Recommendation: upgrade your development clients to 2.51 promptly to take advantage of stash portability and UX stabilization. For servers and very large repositories, run controlled trials of the new repack features and path-walk packing in a mirrored environment and only enable cruft-aware MIDX repacking after verifying disk capacity and client compatibility. The feature set in 2.51 gives maintainers real levers to shrink MIDXes and speed certain operations, but prudent testing remains essential before changing production pack/bitmap generation behavior.
The release continues the steady march toward Git 3.0-era defaults while keeping backward compatibility a top priority — a balance that most teams will appreciate, provided they plan upgrades and maintenance with the usual caution.

---

Source: Tweakers Git 2.51.0