Summary

  • Git's 2018 hash transition design selected SHA-256 and proposed a bidirectional mapping between old and new object names. That mapping was a transition goal, not a working promise to every repository.
  • The Git 2.29.0 manual called SHA-256 repositories experimental in 2020. The Git 2.54.0 manual still states in 2026 that SHA-1 and SHA-256 repositories have no interoperability at present.

A new label rewrites the shelves

Imagine a library where each box bears a fingerprint of its contents. A book can keep its words while receiving a new fingerprint under a new calculation. Git's blob objects resemble that simple case. The trouble starts with the catalogue. A Git tree contains object names for files and subtrees. A commit contains the name of its tree and, usually, its parent commits. Tags can name other objects. The project's transition design spells out the consequence: replace the hash function, and references inside these objects change. Their bytes change; their new names must be calculated from those new bytes. Follow a parent link and the work continues through history.

That is why a switch from SHA-1 to SHA-256 was more than making an identifier longer. Existing tools, stored repositories, remote peers and the names people pasted into issue reports all inhabited the old address space. A new repository could choose a new format, but a mixed world needed a way to say which new name meant the same underlying object as an old one. Hashes cannot themselves answer that question. Someone must build and retain the correspondence.

The 2018 Git design proposed that correspondence as a bidirectional name map. It wanted repository-by-repository conversion and communication with SHA-1 servers while SHA-256 adoption grew. It also described stages of implementation and left new protocol support outside the initial design. These were plans for crossing the bridge, not evidence that the bridge already carried ordinary traffic. The paper was honest about the expense: a graph of content-addressed objects cannot change its naming rule by decree.

The flag arrived before the bridge

The Git 2.29.0 git-init manual offered --object-format=sha256 in 2020. Its warning was unusually plain. SHA-256 repositories were experimental, were intended for testing, and generally could not share work with SHA-1 repositories. The flag made a new kind of local repository possible; it did not make the surrounding ecosystem speak both dialects.

Six years later, the Git 2.54.0 manual still listed sha1 as the default object format and sha256 as an option. It also said there was no interoperability between SHA-256 and SHA-1 repositories at present. The contrast with the 2018 design is the story. Git could specify the destination early and offer a testable new format, while the practical ability to exchange a connected history across formats remained unfinished.

The project's BreakingChanges plan now targets SHA-256 as the default for new repositories in Git 3.0. It gives no release date, ties the move to readiness of libraries, applications and hosting services, and does not plan to retire the SHA-1 object format yet. A default can change when new users enter the system even while old repositories stay on their existing rails. That is a migration strategy with two living populations, not a ceremonial turning of one giant switch.

The cost lived in every reference

SHA-1's weaknesses gave the project a reason to seek a different object name. The transition design discusses the 2017 SHAttered collision and the choice of SHA-256. Yet cryptographic preference could not erase the references embedded in Git's stored objects. The technical decision depended on the rest of the network: a hosting service, a client library or a build tool that could not understand the new format could still hold the door shut.

The proposal's mapping table was an attempt to keep two address systems in conversation while that network caught up. The later manuals expose how hard that bargain is. By 2026, a user could ask Git to start a SHA-256 repository, but the manual still warned about crossing into a SHA-1 repository. The new passport was real; the border office had not finished its forms.

Git's history here is a useful rebuke to the idea that a standard is finished when its replacement algorithm is chosen. In a content-addressed system, names are part of the content, part of the references, and part of other people's tools. The running system gets a vote on the migration schedule.