Reading Digital Successions

Hidos provides basic functionality for reading digital successions.

Digital successions are temporarily stored in local git repositories and persistently stored publicly on Internet servers that are compatible with git. If you created or amended your own digital succession, then you have that digital succession in a local git repository.

The following examples assume your current directory is a local git repository. To use another directory, use the --git-dir option immediately after hidos in the command line.

Basic information using hidos

You can list all digital successions found in a git repository as such:

hidos list

Both a DSI and branch name will be printed for each digital succession. By default only local git branches are displayed. To display all branches use the --all option.

To display only the DSI for a specific branch you can do:

hidos dsi branch_name

and to list all editions along with the SWHID of their binary content, do:

hidos dsi --editions branch_name

To see who is recorded as the creator of a digital succession and the signing key that was used do:

hidos info branch_name

The displayed signature key can then be used with services such as keybase.io, keyoxide.org, and keys.openpgp.org to verify who is the signer.

Reading an edition as file or folder

As of October 2022, reading an edition as a digital object into a local file or folder requires using git directly. If a digital succession is archived, then the digital object can be viewed online.

A digital object can be a file or a directory. After running

hidos dsi --editions branch_name

an SWHID will be listed for each edition. An SWHID starts with swh:1:cnt: or swh:1:dir: for files and directories, respectively.

If the digital object is in the Software Heritage Archive then the SWHID can be appended to https://archive.softwareheritage.org/ to view the digital object.

To read a digital object locally, you can use git. The last part of a SWHID, the suffix following swh:1:cnt: or swh:1:dir: is a git hash. Given the displayed git hash listed for an edition (output by hidos dsi --editions), git can be used to output the digital object:

git show <hash>

If the digital object is a file, the file contents will be output. For a directory, a listing of contained files will be printed. Given a path to a file in the directory, the following will output the file inside the directory:

git show <hash>:<path>