114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# NAME
|
|
|
|
git-remote-annex - remote helper program to store a 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 with an URL that starts with "annex::"
|
|
|
|
The special remote needs to have a `remote.<name>.url`
|
|
configured to use this. That is set up automatically when git
|
|
cloning from a special remote.
|
|
|
|
To make [[git-annex-initremote]](1) and [[git-annex-enableremote]](1)
|
|
configure the url, pass them the `--with-url` option.
|
|
|
|
Or, to configure an existing special remote with a shorthand URL, run:
|
|
|
|
git config remote.name.url annex::
|
|
|
|
Once the URL is configured, you can use `git pull`, `git push`, etc
|
|
with the special remote much like with any other git remote.
|
|
But see CONFLICTING PUSHES below for some situations where it behaves
|
|
slightly differently.
|
|
|
|
# URL FORMAT
|
|
|
|
This uses an URL that starts with "annex::". There are three forms of such
|
|
URLs:
|
|
|
|
* Complete URL
|
|
|
|
This contains the UUID and all configuration parameters
|
|
of the special remote that were passed when using
|
|
`git-annex initremote`.
|
|
|
|
For example, to clone from a directory special remote:
|
|
|
|
git clone annex::358ff77e-0bc3-11ef-bc49-872e6695c0e3?type=directory&encryption=none&directory=/mnt/foo/
|
|
|
|
* Shorthand URL
|
|
|
|
This makes it easy to configure an existing special remote with an URL
|
|
without having to come up with the complete URL.
|
|
|
|
annex::
|
|
|
|
When using this shorthand URL, the full URL will be displayed each time you
|
|
git pull or push, when it's possible for git-annex to determine it.
|
|
(Although in some cases, like the directory special remote, some
|
|
parameters may be left off of the displayed URL.)
|
|
|
|
* Web URL
|
|
|
|
This URL points at a file on the web, which contains the complete annex::
|
|
URL.
|
|
|
|
annex::https://example.com/foo-repo
|
|
|
|
Not all special remotes can be accessed by such an URL,
|
|
for security reasons. Currently, this is limited to httpalso special
|
|
remotes.
|
|
|
|
# CONFLICTING PUSHES
|
|
|
|
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
|
|
situation, the overwritten push will appear to have succeeded, but pulling
|
|
later will show the true situation.
|
|
|
|
# REPOSITORY FORMAT
|
|
|
|
The git repository is stored in the special remote using special annex objects
|
|
with names starting with "GITMANIFEST" and "GITBUNDLE". For details, 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 is re-uploaded. That is done when force
|
|
pushing a ref, or 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>.annex-max-git-bundles` git config.
|
|
|
|
Note that a re-upload of the repository does not delete old GITBUNDLE
|
|
objects from it. This means that refs pushed to the special
|
|
remote can still be accessed even after deleting or overwriting them.
|
|
|
|
A push that deletes every ref from the special remote will delete all
|
|
the accumulated GITBUNDLE objects. But of course, making such a push
|
|
means that someone who clones from the special remote at that point in time
|
|
will see an empty remote.
|
|
|
|
# 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.
|