added man page for git-remote-annex
And document remote.<name>.git-remote-annex-max-bundles which will configure it. datalad-annex uses a similar url format, but with some enhancements. See https://github.com/datalad/datalad-next/blob/main/datalad_next/gitremotes/datalad_annex.py I added the UUID to the URL, because it is needed in order to pick out which manifest file to use. The design allows for a single key/value store to have several special remotes all stored in it, and so the manifest includes the UUID in its name. While datalad-annex allows datalad-annex::<url>?, and allows referencing peices of the url in the parameters, needing the UUID prevents git-remote-annex from supporting that syntax. And anyway, it is a complication and I want to keep things simple for now. Sponsored-by: unqueued on Patreon
This commit is contained in:
Joey Hess
parent
90b389369f
commit
a8cef2bf85
2 changed files with 90 additions and 0 deletions
|
|
@ -1644,6 +1644,17 @@ Remotes are configured using these settings in `.git/config`.
|
|||
remotes, and is set when using [[git-annex-initremote]](1) with the
|
||||
`--private` option.
|
||||
|
||||
* `remote.<name>.git-remote-annex-max-bundles`
|
||||
|
||||
When using [[git-remote-annex]] to store a git repository in a special
|
||||
remote, this configures how many separate git bundle objects to store
|
||||
in the special remote before re-pushing a single git bundle that contains
|
||||
the entire git repository.
|
||||
|
||||
The default is 100, which aims to avoid often needing to often re-upload,
|
||||
while preventing a new clone needing to download too many objects. Set to
|
||||
0 to disable re-pushing.
|
||||
|
||||
* `remote.<name>.annex-bare`
|
||||
|
||||
Can be used to tell git-annex if a remote is a bare repository
|
||||
|
|
|
|||
79
doc/git-remote-annex.mdwn
Normal file
79
doc/git-remote-annex.mdwn
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# NAME
|
||||
|
||||
git-remote-annex - remote helper program to store git repository in a git-annex special remote
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
git fetch annex::uuid?param=value¶m=value...
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
This is a git remote helper program that allows git to clone,
|
||||
pull and push from a git repository that is stored in a git-annex
|
||||
special remote.
|
||||
|
||||
It can be used with any special remote except those that use
|
||||
encryption=shared or encryption=hybrid. (Since those types of encryption
|
||||
rely on on cipher that is checked into the git repository, cloning from
|
||||
such a special remote would present a chicken and egg problem.)
|
||||
|
||||
The format of the remote URL is "annex::" followed by the UUID of the
|
||||
special remote, and then followed by all of the configuration parameters of
|
||||
the special remote.
|
||||
|
||||
For example, to clone from a directory special remote:
|
||||
|
||||
git clone annex::358ff77e-0bc3-11ef-bc49-872e6695c0e3?type=directory&encryption=none&directory=/mnt/foo/
|
||||
|
||||
When a special remote needs some additional credentials to be provided,
|
||||
they are not included in the URL, and need to be provided when cloning from
|
||||
the special remote. That is typically done by setting environment
|
||||
variables. Some special remotes may also need environment variables to be
|
||||
set when pulling or pushing.
|
||||
|
||||
As a useful shorthand, when the special remote has already been enabled,
|
||||
the configuration parameters can be omitted. For example:
|
||||
|
||||
git push annex::358ff77e-0bc3-11ef-bc49-872e6695c0e3 master
|
||||
|
||||
This also makes it easy to configure git to use an existing special remote:
|
||||
|
||||
git config remote.foo.url annex::358ff77e-0bc3-11ef-bc49-872e6695c0e3
|
||||
git fetch foo master
|
||||
|
||||
Configuring the url like that is automatically done when cloning from a
|
||||
special remote, but not by [[git-annex-initremote]](1) and
|
||||
[[git-annex-enableremote]](1).
|
||||
|
||||
The git repository is stored in the special remote using special annex objects
|
||||
with names starting with "GITMANIFEST--" and "GITBUNDLE--". For details about
|
||||
how the git repository is stored, see
|
||||
<https://git-annex.branchable.com/internals/git-remote-annex/>
|
||||
|
||||
Pushes to a special remote are usually done incrementally. However,
|
||||
sometimes the whole git repository (but not the annex) needs to be
|
||||
re-uploaded. This is done when deleting a ref from the remote. It's also
|
||||
done when too many git bundles accumulate in the special remote, as
|
||||
configured by the `remote.<name>.git-remote-annex-max-bundles` git config.
|
||||
|
||||
Like any git repository, a git repository stored on a special remote can
|
||||
have conflicting things pushed to it from different places. This mostly
|
||||
works the same as any other git repository, eg a push that overwrites other
|
||||
work will be prevented unless forced. However, it is possible, when
|
||||
conflicting pushes are being done at the same time, for one of the pushes
|
||||
to be overwritten by the other one. In this sitiation, the push will appear
|
||||
to have succeeded, but pulling later will show the true situation.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
gitremote-helpers(1)
|
||||
|
||||
[[git-annex]](1)
|
||||
|
||||
[[git-annex-initremote]](1)
|
||||
|
||||
# AUTHOR
|
||||
|
||||
Joey Hess <id@joeyh.name>
|
||||
|
||||
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
|
||||
Loading…
Reference in a new issue