git-annex/doc/internals/git-remote-annex.mdwn
Joey Hess 3e7324bbcb
only delete bundles on pushEmpty
This avoids some apparently otherwise unsolveable problems involving
races that resulted in the manifest listing bundles that were deleted.

Removed the annex-max-git-bundles config because it can't actually
result in deleting old bundles. It would still be possible to have a
config that controls how often to do a full push, which would avoid
needing to download too many bundles on clone, as well as needing to
checkpresent too many bundles in verifyManifest. But it would need a
different name and description.
2024-05-21 11:13:27 -04:00

55 lines
2.1 KiB
Markdown

The [[git-remote-annex|/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.)
Note that, if a 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 when a push is made to the remote that
deletes all refs from it, and in a race between such a push and another
push of some refs, it is possible for the GITMANIFEST to refer to deleted
bundles.
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|tips/Decrypting_files_in_special_remotes_without_git-annex]].