The git-remote-annex command allows pushing a git repository to a special remote, and later cloning from it.

This adds two new key types to git-annex, GITMANIFEST and a GITBUNDLE.

GITMANIFEST--$UUID is the manifest for a git repository stored in the git-annex repository with that UUID. When that is not present, GITMANIFEST--$UUID.bak is a backup copy that can be used instead.

GITBUNDLE--$UUID-$sha256 is a git bundle.

format of the manifest file

An ordered list of bundle keys, one per line.

Additionally, there may be bundle keys that are prefixed with "-". These keys are not part of the current content of the git remote, and are in the process of being deleted.

(Lines end with unix "\n", not "\r\n".)

exporttree=yes remotes

In an exporttree=yes remote, the GITMANIFEST and GITBUNDLE objects are stored in the remote, under the .git/annex/objects/ path.

multiple special remotes in the same place

It's possible for multiple special remotes to point to the same object storage.

This is why the UUID of the special remote is included in the GITMANIFEST key, and in the annex:: uri.

manually cloning from these files

If you are unable to use git-annex and need to clone a git repository stored in such a special remote, this procedure will work:

  • Find and download the GITMANIFEST
  • Download each listed GITBUNDLE
  • git fetch from each new bundle in order. (Note that later bundles can update refs from the versions in previous bundles.)

If any GITBUNDLE listed in the GITMANIFEST turns out not to exist, a clone should treat this the same as if the GITMANIFEST were empty. Bundle objects are deleted only when a push is made to the remote that deletes all refs from it, and when there was a race between such a push and another push of some refs, it is possible for the GITMANIFEST to refer to deleted bundles. In such a situation, the push that deleted all refs wins. (This race condition is why old GITBUNDLE objects are listed in the manifest rather than being immediately deleted.)

When the special remote is encrypted, both the names and content of the GITMANIFEST and GITBUNDLE will also be encrypted. To decrypt those manually, see this fairly simple shell script using standard tools.