The long-term goal is to collect all publicly available software in source code form together its development history, replicate it massively to ensure its preservation, and share it with everyone who needs it.

For more information about the Software Heritage mission.

Here is an excerpt of this list:

• Git repositories from multiple forges (GitHub, Bitbucket, GitLab instances, cgit instances, Gitea instances, Phabricator instances, etc.)
• SVN repositories…
• Mercurial repositories…
• Debian packages in apt
• Python packages in PyPI
• R packages in CRAN
• NPM packages in npm.org
• zip or archives tarballs in gnu.org

If it is not there yet, or if the latest snapshot is not the most recent state of your repository, you can trigger a new archival using the Save Code Now functionality
https://archive.softwareheritage.org/save/ or by clicking on the « Save again » button in the browse view.

A GitHub action is available to automatically push a save code now request. Here is an example of this action configured to run each time a new release is issued.

You can also use the browser extension.

The reason for this approach is because the value of software source code cannot be known in advance. When a project starts, one cannot predict whether it will become a key software component or not. For example, when Rasmus Lerdorf released the first version on PHP back in 1995, who could have predicted that it would become one of the most popular tools for the Web.

And it also happens that very precious pieces of source code may be go unnoticed for decades, until one day some unexpected bug unveils that a big part of our digital infrastructure relies on them.

Let’s say you tagged your release naming it « FinalSubmission », but you did not use an annotated tag: in this case, it will not show up in the Releases tab on Software Heritage, but it is there nonetheless! Click on the branch dropdown menu on the Software Heritage Web interface and you’ll find it listed as « refs/tags/FinalSubmission ». If you want a release to appear in our web interface you should create your tags
using « git tag -a », instead of simply « git tag », or create the release directly on the code hosting platform, that uses the proper « git tag -a » behind the scenes, and then archive your
repository again.

Details about the syntax, semantics, interoperability, and implementation can be found in the formal specification.

The following diagram shows concisely the key components of an SWHID:

The top yellow box in the diagram corresponds to the « core SWHID. » You can add qualifiers to a core SWHID to specify the location of a software artifact within the Software Heritage Archive or to identify specific code fragments within it.

A core SWHID can be used to identify the following source code artifacts:

• File contents  Example: swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2 points to the content of a file containing the full text of the GPL3 license
• Directories  Example:  swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505 points to a directory containing the source code of the Darktable photography application as it was at some point on May 4, 2017
• Revisions (a.k.a commits) Example: swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d points to a commit in the development history of Darktable, dated 16 January 2017, that added undo/redo supports for masks
• Releases  Example: swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f points to Darktable release 2.3.0, dated 24 December 2016
• Snapshots Example: swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453 points to a snapshot of the entire Darktable Git repository taken on 4 May 2017 from GitHub

Using the lines qualifier, you can also identify code fragments or specific selections of code. For example, use swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2;lines=4-6 pinpoint lines four to six of the full text of the GPL3 license.

More generally, using a fully qualified SWHID provides all relevant information for placing a software artifact in context. For instance, the SWHID below pinpoints the core mapping algorithm contained in the file parmap.ml, located in the src directory of a specific revision of the Parmap project retrieved from https://github.com/rdicosmo/parmap

swh:1:cnt:3b997e8ef2e38d5b31fb353214a54686e72f0870;origin=https://github.com/rdicosmo/parmap;visit=swh:1:snp:25490d451af2414b2a08ece0df643dfdf2800084;anchor=swh:1:rev:db44dc9cf7a6af7b56d8ebda8c75be3375c89282;path=/src/parmap.ml;lines=192-237

The « Permalinks » tab provides the SWHID for the content you are viewing. Here’s an example:

Click « Copy identifier » to get the SWHID in your clipboard. Clicking « Copy permalink » will copy the corresponding URL.

The « Add contextual information » checkbox allows you to choose whether you will get a core SWHID or the SWHID with the extra qualifiers that provide contextual information.

The Permalinks tab offers multiple SWHID options depending on the level of code you need to reference. You can get an ID for a file, a directory, a revision, a release, or an entire snapshot. To find the best option for your use case, see the next question.

When writing a research article, blog post, or technical documentation, you’ll often face a trade-off: providing a complete reference with the full SWHID or keeping the reference short due to space limitations.

Here’s the recommended best practice for this issue:

1. get the full SWHID for the ‘directory’ containing the version of the code you want to reference. Here is an example of such a full SWHID:
   swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e
2. ensure the « core SWHID » (swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18 in the example above) is printed, and the full SWHID is available at least as an hyperlink.

Here’s how to do it in LaTeX:

href{https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/}{swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18}

or in Markdown:

[swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18](https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/)

This approach ensures that readers can find the most useful identifier for reproducibility: the core SWHID of the directory. Because this ID is computed locally from the code’s content, it remains the same regardless of which release or commit the directory belongs to.

In a digital version, the link uses the full SWHID to let readers browse the code in Software Heritage with all of its relevant context, such as its version and origin.

All software components present in the Archive may be covered by copyright, or other rights like patents or trademarks. Software Heritage may provide automatically derived information on the software license(s) that may apply to a given software component, but it makes no claim of correctness and the licence information provided does not constitute legal advice. You are solely responsible for determining the license, or other rights that apply to any software component in the Archive, and you must abide by its terms.

Software Heritage stores all the software artifacts in a massive shared Merkle tree, so that exporting (a specific version of) an archived respository implies traversing the graph to get all the relevant contents and packaging them up for your consumption. This operation is much more expensive than downloading an existing tar file or cloning a repository from a forge.

If really Software Heritage is your last resort, and you cannot find the source code of interest elsewhere, we recommend that you download only the version of interest for you, using the « directory » option of the Download button that you find when you browse the archive.

If absolutely needed, you can use the more expensive « revision » option of the Download button, that will prepare for you the equivalent of a git bare clone , which you will be able to use offline. This may require quite some time (hours, or even days for huge repositories).

• /api/1/snapshot/ which allows you to get the snapshot’s branches and tags, each with a target_url key that contains the URL to
• /api/1/release/ or /api/1/revision/ which allow you to get the revision’s or releases’ data. Assuming you get a revision, the directory_url key contains a URL to:
• /api/1/directory/ which lists entries of the root directory, with links to other directories and content objects
• /api/1/content/ which returns all the information about a given file content, including a link to the raw data.

You can also lookup an origin, and follow its visits:

• /api/1/origin/search/ allows you to search the exact URL of the code repository
• /api/1/origin/visits/ allows you to list the times Software Heritage visited the repository, and get the snapshot associated with each visit. For each visit, this snapshot is available as a snapshot_url key, that contains the URL to get the corresponding snapshot object.

If you are interested in downloading a large part of the repository (a directory or a set of revisions), you should use the download service called the Vault. The Vault allows you to fetch them in batch and download a tarball. The list of vault endpoints is available at the end of the list of all API endpoints

Follow the Software Heritage guidelines on how to prepare your code for archival.

More information about the formats that are indexed and some general overview of the metadata workflow in the blog-post about mining for software metadata

For example, the French HAL national open access archive looks for a codemeta.json file when a software project archived in Software Heritage is deposited, and pre-fills the deposit form using the information it contains, a real time saver!

Last but not least, Software Heritage indexes the metadata contained in codemeta.json files and makes it searchable on the web-app using the CodeMeta crosswalk table. The crosswalk table is the Rosetta stone of software metadata, facilitating translation between ontologies and metadata standards for software.