# 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&param=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.