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>

                                                                                             git-remote-annex(1)