git-annex/ special remotes/ gcrypt

git-remote-gcrypt adds support for encrypted remotes to git. The git-annex gcrypt special remote allows git-annex to also store its files in such repositories. Naturally, git-annex encrypts the files it stores too, so everything stored on the remote is encrypted.

This special remote needs the server hosting the remote repository to either have git-annex-shell or rsync accessible via ssh. git-annex uses those to store its content in the remote. If the remote repository is instead hosted on a server using git-lfs, you can use the git-lfs special remote instead of this one; it also supports using gcrypt.

See fully encrypted git repositories with gcrypt for some examples of using gcrypt.

## configuration

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

- `encryption` - One of "none", "hybrid", "shared", or "pubkey". Required. See encryption.

- `keyid` - Specifies the gpg key to use for encryption of both the files git-annex stores in the repository, as well as to encrypt the git repository itself. May be repeated when multiple participants should have access to the repository.

- `gitrepo` - Required. The location of the git repository for gcrypt to use. This repository should be either an unpopulated bare git repo, or an existing gcrypt repository.

  To use a local git repository, use: `gitrepo=/path/to/repo`

  For a git repository accessed over ssh, an `rsync://` url uses rsync over ssh, while a `ssh://` url uses git-annex-shell over ssh. Note that each `git push` has to re-send the whole content of the git repository when using the latter option, so rsync urls are generally more efficient.

- `chunk` - Enables chunking when storing large files.

- `shellescape` - See rsync for the details of this option.

## notes

For git-annex to store files in a repository on a remote server, you need shell access, and it needs to be able to run `rsync` or `git-annex-shell`.

If you can't run `rsync` or `git-annex-shell` on the remote server, you can't use this special remote. Other options are the git-lfs special remote, which can also be combined with gcrypt, or using git-remote-gcrypt to encrypt a remote that git-annex cannot use.

If you use encryption=hybrid, you can later add more gpg keys that can access the files git-annex stored in the gcrypt repository. However, due to the way git-remote-gcrypt encrypts the git repository, you will need to somehow force it to re-push everything again, so that the encrypted repository can be decrypted by the added keys. Probably this can be done by setting `GCRYPT_FULL_REPACK` and doing a forced push of branches.

Recent versions of git-annex configure `remote.<name>`gcrypt-publish-participants` when setting up a gcrypt repository. This is done to avoid unnecessary gpg passphrase prompts, but it does publish the gpg keyids that can decrypt the repository. Unset it if you need to obscure that.

comment 3

@tomdhunt, Are you saying that the difference is the rsync remote only contains the files and the actual history stuff from git isn't tracked in it while the git-remote-gcrypt one also tracks history because it is a bare git repo?

Additionally, I just started trying out the grcrypt version on rsync.net and it seems to use a slightly different initialization when compared to the others. I've made some progress, but I am still not quite able to make it work, it seems that I'm having issues initializing the bare remote when I do it via the terminal. If I don't try to create a bare and push it the first commit completely fails, I seem to be able to make more progress by creating a bare, pushing it, and then adding it (but it still fails). This is what I have got to so far:

    user@localhost:$ sudo chown <rsync.net user>:<rsync.net user> -R
    user@localhost:$ git init --bare shared=group test_repo.git
    user@localhost:$ sudo rsync -vrSP test_repo.git <rsync.net user>@<server>:annex
    user@localhost:$ git annex initremote "<some_userful_name>" type=gcrypt gitrepo=<rsync.net user>@<server>:annex chunk=1MiB keyid=<key_id> encryption=shared mac=HMACSHA512 autoenable=true

The error message that I get:

    user@localhost:$ git annex sync
    commit
    On branch master

    Initial commit

    nothing to commit (create/copy files and use "git add" to track)
    ok
    pull <rsync.net server>
    gcrypt: Decrypting manifest
    gpg: selecting card failed: No such device
    gpg: Signature made Sun 09 Jan 2022 08:26:18 AM GMT
    gpg:                using EDDSA key <key>
    gpg: Good signature from "<key comment>" [ultimate]

    merge: refs/remotes/<remote name>/master - not something we can merge

    merge: refs/remotes/<remote name>/synced/master - not something we can merge
    failed
    sync: 1 failed

It also looks like this method fails to add `gcrypt-participants = <key>` and `gcrypt-signingkey = <key>` to the `.git/config` file like webapp does.

Furthermore, when I use the `git annex webapp` to generate the repo, it does something that seems to be even more different (and successfully creates the bare repo by itself), specifically the URL looks something like this:

    url = gcrypt::<rsync.net user>@git-annex-.<country>.2D<server_subname?>.2E<server_name>.2E<server_domain>-<rsync.net user>_22_annex:annex/

It seems to be encoding some of the characters to make a URL? Is there another web API that we can interact with?

Comment by aaron — Tue Jul 22 18:11:47 2025
comment 2

The gcrypt special remote is for use with the git-remote-gcrypt protocol for making encrypted git remotes. The rsync special remote can also encrypt the files it stores, but it's not related to git-remote-gcrypt; it just puts files in a plain directory tree using rsync.

If you want to keep a repository remote (not a special remote) on your rsync.net host, and want it to be encrypted, then you can use git-remote-gcrypt and use this special remote so that the data is all together. If you're not using git-remote-gcrypt, then the rsync special remote is what you want.

Comment by tomdhunt — Tue Jul 22 18:11:47 2025
How does the gcrypt type compare to the rsync special remote
For systems (such as rsync.net) that allow us to use both rsync and git-annex, which is the better option? I noticed that the default for rsync.net was this type (gcrypt), does it provide additional capabilities or perform slightly better than the rsync version?
Comment by aaron — Tue Jul 22 18:11:47 2025
Comments on this page are closed.