git-annex/ special remotes/ borg

This special remote type accesses annexed files stored in a borg 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.

comment 2

I have opened a bug for that issue, borg special remote memory usage high for large borg repo.

It would be good if you could followup there with details.

Comment by joey — Wed Oct 29 14:05:27 2025
Memory issues

When I tried running `git annex sync borg` on a large (~6T) borg repo with many archives, git-annex spun until it used 52G of memory, then got OOM-killed.

I don't know if this is a memory leak or just trying to load too much, but it seems like this is a thing you should be able to do on a machine with 64G of RAM.

Comment by tomdhunt — Wed Oct 29 14:05:27 2025
Comments on this page are closed.