I'm using git-annex in version 7.20190129 as it is provided on my Debian Stable (Buster) machine to keep big files under version control and have them distributed over multiple machines and drives. This works well as long as I have at least one "real" git-annex repository (not a special remote).

What I'd be interested in is using just one git annex repository on my local machine and additionally special remotes (e.g. the bup special remote or the rsync special remote or, as soon as it lands on Debian Stable, the borg special remote).

My workflow is as follows:

cd /path/to/my/local/folder
git init
git annex init
git annex add myawesomefile
git commit -m 'this works on my local repository'
git annex initremote mybupbackuprepo type=bup encryption=none buprepo=/path/to/my/special/remote/location
git annex sync
git annex copy files --to mybupbackuprepo

Then I'm able to use my bup special remote as I would use an additional repository.

But now I'd like to access my bup repo without using the first, local repo (e.g. in case my local machine would break down). As far as I understood (from following the official guide, the following should work:

cd /path/to/new/folder/to/extract/the/backup
git init
git annex init
git annex initremote mybupbackuprepo type=bup encryption=none buprepo=/path/to/my/special/remote
git annex enableremote mybupbackuprepo
git annex sync

But I'm still not able to see any files (or even some broken symlinks) and, obviously, also not able to get any of my data when using git annex sync --content or git annex get myawesomefile.

Any ideas? What am I missing?

1 Answer 1


A special remote is just storing the file data, not the git repository. Think of it as a a library's cellar: A library may build an additional room to store its books there, but if you want to build a library back from the cellar, you don't have any index, don't know which book is in which catalogue, and you don't have a librarian that can help you find your books.

So in practice, you will need another git repository to replicate the master branch, which contains all the information about what goes where.

In cases like yours (where you host that storage yourself), you don't need any special remote then -- the regular (typically but not necessarily bare) git repository you use as your origin can also store the large files, and can be used by a later checkout just as

$ git clone ssh://host/path/repo
$ cd repo
$ git annex init
$ git annex get --from origin

(where the --from origin is more for illustration; if you leave it off, git annex will know what to do as well).

In many cases you don't even need a special remote then; reasons to use a special remote are:

  • You want to split the (small but often needed) git access from data access (large amounts of data), and your data hoster gives you just rsync (or webdav or s3 or whichever protocol) access, not full shell access
  • Your git hoster gives you just bare git, and does not have git-annex installed (eg. GitLab) -- then you need an extra data hoster
  • You need any special properties of the backend (like deduplication across repositories, which only works as long as you don't use encryption)

In most cases (like, it seems, yours), just using a regular git remote and annex-copying data there is just as good, less a hassle to set up, and most importantly you need one anyway to recover your data.

  • thanks a lot for that awesome explanation!
    – n0542344
    Commented Jan 13, 2021 at 10:44

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .