Software Heritage archives code by identity, not by address

The Software Heritage community at UNESCO headquarters in February 2023. The people, venue, and preservation banner are a useful counterweight to the archive's planetary numbers: durability is an institutional practice as well as a storage design. Photograph by Inria/B. Fourrier.[7]

A repository URL answers a fragile question: where can I reach this project today? Software Heritage is built to answer a harder one: which exact source artifact did you mean, even if its host, branch name, or surrounding project later changes?

That distinction makes Software Heritage more interesting than the phrase “GitHub backup” suggests. It crawls public code hosts and package repositories, records successive visits, transforms many version-control formats into a common object model, and assigns intrinsic identifiers to the files, directories, revisions, releases, and repository snapshots it preserves.[1][2] The result is not another forge. It is a source-code archive whose basic unit is an object with an identity, not a page at an address.

The scale is already infrastructural. When this article was prepared in August 2026, the archive's public counters reported more than 29 billion content objects, 6 billion revisions, and 438 million origins.[6] Yet the project's 2026 roadmap says GitHub is growing faster than its present ingestion capacity and reports a lag of more than 140 million origins.[5] Both facts matter. Software Heritage is enormous, active, and uniquely useful; it is not an instantaneous copy of every public repository.

The cover photograph shows members of the community gathered at UNESCO headquarters during a 2023 symposium on source code as documentary heritage.[7] It is deliberately a picture of people in a room, not server racks or a fake “code cloud.” An archive designed to outlast hosting companies depends on maintainers, memory institutions, funding, standards, and succession as surely as it depends on hashes.

A visit turns a location into evidence

Software Heritage begins with an origin: the place from which source code can be obtained, usually a repository or package URL. A lister enumerates origins on a forge or distribution service. A scheduler decides which ones should be visited, while a loader speaks the origin's actual format—Git, Mercurial, Subversion, a package archive, and others—and inserts the recovered objects and relationships into the archive.[1]

This pipeline separates three facts that ordinary forge browsing tends to collapse:

the origin says where material was observed;
a visit says when the archive looked there and whether loading succeeded;
a snapshot says what set of visible branches or references the visit found.[2]

Suppose a library moves from one forge to another, a distribution mirrors it, and fifty downstream projects vendor an identical file. Those locations are meaningful provenance, but they do not create fifty different file contents. Software Heritage can retain multiple paths by which the material was observed while representing the identical artifact once. Conversely, a familiar URL is not proof that its current main branch still contains the source a paper, audit, or release note meant to cite.

This is the first practical reason to use the archive: it converts a mutable location into a dated observation. A successful visit is stronger evidence than a bookmark, but it is still a snapshot of what the crawler could see at that moment. A queued Save Code Now request is therefore not the same as a completed archival visit, and an origin absent from the latest crawl should not be assumed preserved merely because its host is popular.[1][5]

The graph gives source code a shelf mark

At the archive's center is a Merkle directed acyclic graph. File contents sit at the leaves. Directories point to contents and other directories; revisions point to directory states and parent revisions; releases point to revisions; snapshots collect the references observed at an origin. Forks and merges make this a graph rather than a single tree. Nodes are deduplicated by intrinsic identifiers, so repeated files and shared history do not have to be stored anew for every repository that contains them.[2]

Software Heritage identifiers, or SWHIDs, expose that model. Their core form begins swh:1:, followed by an object type such as cnt for file content, dir for a directory, rev for a revision, rel for a release, or snp for a snapshot, and then a cryptographic object identifier. A core SWHID can be computed from the artifact itself; it is an identifier rather than a URL, though resolvers can turn it into a browsable archive page.[3]

The choice of object type is consequential. A file-content SWHID identifies bytes but forgets the filename and surrounding tree. A directory SWHID captures a source tree and can be recomputed even if higher-level version-control metadata is gone. The project's specification consequently recommends directory identifiers for robust source references, accompanied where possible by an anchor that reconnects the tree to a release or revision.[3]

Qualifiers restore context without weakening intrinsic identity. An identifier may carry the origin, the snapshot associated with a visit, an anchor in the graph, a path, and even a line range. That lets a research paper point to a precise passage while retaining the chain back to the observed repository.[3] The hash answers “which artifact?”; the qualifiers answer “in which recorded setting?”

There is also a critical negative boundary. A matching SWHID establishes artifact identity. It does not establish who authored the code, whether its license permits a planned use, whether it is free of vulnerabilities, whether the repository was compromised before archival, or whether the source still builds. Those are claims about provenance, policy, security, and environment. The archive supplies unusually strong evidence for them, but the hash does not decide them.

The archive is a fleet, not one database

The public graph metaphor can hide the machinery required to keep it useful. In the production architecture, source blobs live in content-addressable object storage on Ceph behind a workload-specific layer called Winery. Graph structure and metadata are served from Cassandra. A Kafka journal records additions so dependent services and mirrors can follow the stream. Elasticsearch supports origin-URL search, while a separate compressed-graph service accelerates graph traversal. Even the public counters use HyperLogLog estimates rather than repeatedly counting billions of rows.[1]

These components embody different workload shapes. Ingestion is a continuous, failure-prone conversation with thousands of external services. Immutable blobs favor deduplication and append-heavy storage. Provenance and graph edges need structured queries. Mirrors need an ordered stream of change. Reconstructing a repository for a reader is different again.

The 2026 roadmap is valuable precisely because it does not turn this architecture into mythology. It says some infrastructure is copied to mirrors but lacks tooling for a fast restoration after a catastrophic failure; it prioritizes proper backups and easier recovery. It also names the GitHub ingestion backlog, automated graph compression, and future Git SHA-256 support as unfinished work.[5] For an adopter, these are healthy maintenance signals—specific owners and technical debts are visible—but also boundary conditions. “Preserved” should not be translated into a zero-recovery-time guarantee.

Software Heritage also cannot be literally append-only in every public view. Its architecture includes blocking and masking paths for takedown requests, plus mechanisms to alter exposed personal identity information.[1] Long-term preservation has to coexist with legal and human obligations. A durable reference is designed to survive ordinary platform churn; it is not a promise that no exceptional removal or masking process can ever apply.

Recovery has to be cooked

Deduplication makes individual objects addressable, but it means a familiar repository bundle may not be waiting as one ready-made file. The Vault assembles, or “cooks,” related objects asynchronously. It can prepare a flat tar archive, a Git fast-export stream, or a bare Git repository, depending on the requested object and desired reconstruction. Requests move through states such as new, pending, done, and failed; cooked bundles are cached, expire, and may need to be prepared again.[4]

That behavior reveals the archive's honest operational role. It is excellent as an independent preservation and verification layer. It is a poor substitute for a low-latency clone mirror in a deployment pipeline. If losing a forge at 09:00 must not interrupt a release at 09:05, keep your own tested mirror or backup. If you need to prove which tree a 2024 paper analyzed after its repository disappears in 2034, a qualified SWHID and a tested Vault retrieval are much closer to the right tool.

Retrieval also cannot recreate context that was never source code. Issue discussions, CI logs, package-signing keys, hosted release binaries, external datasets, secrets, container registries, and third-party services may be essential to operating a project even when its source tree is intact. The core Software Heritage model preserves source artifacts, history, and observation provenance; teams should export or preserve the rest of their collaboration and runtime surface separately.[1][2]

A small preservation contract

For a team publishing open source, adoption can stay narrow and testable:

Archive a deliberate state. After a meaningful release, verify that the public origin has a successful visit. Use Save Code Now when necessary, but wait for completion rather than recording only the request.
Record the artifact, not just the branch. Capture a directory SWHID for the released source tree and keep an anchor to the corresponding revision or release. Add origin and visit context when the reference will be shared.[3]
Exercise retrieval. Request the relevant Vault bundle, restore it somewhere empty, and confirm the tree or repository resolves to the expected identifier.[4]
Preserve the operating envelope. Keep dependency locks, toolchain versions, build instructions, external data references, and any required binary artifacts in an appropriate archive or backup. A source identity is the foundation of reproducibility, not the whole building.
Retain a faster recovery path when downtime matters. Software Heritage adds institutional and technical independence; it does not remove the need for a backup with a recovery objective your team has actually measured.[5]

This contract is especially strong for research releases, public-sector code, historical projects, and small foundations that cannot guarantee one forge will exist forever. It is also cheap to add alongside normal Git practice because it does not ask the archive to become the development platform. The forge can remain optimized for collaboration. Software Heritage can remain optimized for memory.

That division of labor is the project's real introduction. URLs name doors. Branches name moving pointers. A Software Heritage identifier names an artifact, while visits and qualifiers preserve the trail back to a place and time. The archive becomes useful when those layers are kept distinct—and trustworthy when its own lag, recovery work, and institutional dependencies remain visible.

cronfeed.work