git-annex/ special remotes/ bittorrent

Similar to the web special remote, git-annex can use BitTorrent as a source for files that are added to the git-annex repository.

It supports both `.torrent` files, and `magnet:` links. When you run `git annex addurl` with either of these, it will download the contents of the torrent and add it to the git annex repository.

See using the web as a special remote for usage examples.

git-annex uses aria2 to download torrents.

If git-annex is not built using the haskell torrent library to parse torrents, it also needs the `btshowmetainfo` program, from either bittornado or the original BitTorrent client.

The bittorrent special remote is always enabled, without any manual setup being needed. Its name is "bittorrent".

## notes

Currently git-annex only supports downloading content from a torrent; it cannot upload or remove content.

Multi-file torrents are supported; to handle them, `git annex addurl` will add a directory containing all the files from the torrent.

It's hard to say if a torrent is healthy enough to let a file be downloaded from it, and harder to predict if a torrent will stay healthy. So, git-annex takes a cautious approach and when dropping a file, won't treat this special remote as one of the required copies. It's probably a good idea to configure git-annex to fully distrust this remote, by running `git annex untrust bittorrent`

comment 4

annex.security.allowed-url-schemes can be configured to allow using file: urls.

However, adding a temp file as an url does not seem very useful. Seems that a much more typical bittorrent way to go would be to find or generate a magnet: url for the torrent.

Comment by joey — Tue Jul 22 18:11:47 2025
workaround not working any more
The workaround I described above ceased to work when git-annex or aria2c got configured more strictly; attempting it now gives a "download failed: Configuration does not allow accessing" error message – that is understandable in a way (redirects from web pages should really not make git-annex access local files), but leaves wzhd's problem open again.
Comment by https://christian.amsuess.com/chrysn — Tue Jul 22 18:11:47 2025
Re: attaching a torrent file to a downloaded and annexed directory
wzhd, you can do `git annex addurl file:///full/path/to/file.torrent`. this has the downside of denoting a local file that may vanish or not be present at the same location in another checkout, but then again, same goes for http uris. (i'd rather like the torrent file or at least the info part thereof present in git or git-annex; adding the torrent with `addurl --raw` and then using its `file://` url at least gives all the data needed to use the torrent again).
Comment by http://christian.amsuess.com/chrysn — Tue Jul 22 18:11:47 2025
attaching a torrent file to a downloaded and annexed directory

I have a multi-file torrent that has been downloaded and annexed. After reading the article about web remote, I thought `git-annex addurl --file` could be used. However, when I tried `git-annex addurl --file video/tvseries/someseries /tmp/some.torrent`, I get the error

    addurl video/tvseries/someseries git-annex: video/anime/tvseries/someseries already exists and is not annexed; not overwriting

Attaching the torrent to one of the files inside failed, too, with the message:

    addurl video/tvseries/someseries/someepisode.mkv
    while adding a new url to an already annexed file, failed to verify url exists: /tmp/some.torrent
    failed
    git-annex: addurl: 1 failed

Comment by wzhd — Tue Jul 22 18:11:47 2025
Comments on this page are closed.