git-annex/doc/special_remotes/borg.mdwn

This special remote type accesses annexed files stored in a
[borg](https://www.borgbackup.org/) repository.

Unlike most special remotes, git-annex cannot be used to store annexed
files in this special remote. You store files by using `borg create` to
store the git-annex repository in borg. Then `git-annex sync` will learn
about the annexed files that are stored in the borg repository.

## setup example

	# borg init --encryption=keyfile /path/to/borgrepo
	# git annex initremote borg type=borg borgrepo=/path/to/borgrepo
	# borg create /path/to/borgrepo::{now} `pwd`
	# git annex sync borg

## configuration

These parameters can be passed to `git annex initremote` to configure the
remote:

* `borgrepo` - The location of a borg repository, eg a path, or
  `user@host:path` for ssh access.

* `subdir` - The subdirectory within the borg repository where git-annex
  should look for annex object files. The default is to look through the
  whole borg repository.

  This is useful to avoid learning about annex objects in the borg
  repository that belong to unrelated git-annex repositories. It can also
  make syncing faster.

* `appendonly` - You could use borg to delete content from the
  repository at any time, so this defaults to "no", which 
  makes the remote be untrusted. If you set to "yes", you must
  take care to avoid using commands like `borg delete`,
  `borg prune` with the borg repository.

## avoid archive name reuse

Borg repositories contain archives, and git-annex assumes that, once
created, the content of an archive does not change. So if you delete an
archive and then create a new archive with the same name, it will confuse
git-annex about what is contained in the borg repository. So will using
`borg recreate` to remove files from an archive.