# 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.

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/

But you don't need to generate such an url yourself. Instead, you can use
the shorthand url of "annex::" with an existing special remote.

    git-annex initremote foo type=directory encryption=none directory=/mnt/foo
    git config remote.foo.url annex::
	git push foo master

Configuring the url like that is automatically done when 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.

When using the shorthand "annex::" url, the full url will be displayed
each time you git pull or push, when it's possible for git-annex to
determine it.

# 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.

# HTTP ACCESS

If the content of a special remote is published via http, a httpalso
special remote can be initialized, and used to `git clone` and `git fetch`
over http.

For example, if the directory special remote set up above is published
at `https://example.com/foo/`, set up the httpalso remote like this
to access it:

    git-annex initremote foohttp --with-url --sameas=foo type=httpalso url=https://example.com/foo/

Be sure to remember to include exporttree=yes if the remote is configured
that way.

Once a httpalso remote is set up like this, `git fetch` from it to display
its full annex:: url. That url can be shared with others to let them clone
the repository.

# 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.