git-annex/doc/special_remotes/gcrypt.mdwn

[git-remote-gcrypt](https://spwhitton.name/tech/code/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 [[tips/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 using rsync over ssh, use:
  `gitrepo=rsync://user@host/path/to/repo`

  For a git repository accessed over ssh, and using git-annex-shell
  to transfer data, use:
  `gitrepo=ssh://user@host/path/to/repo` or `gitrepo=host:path`  
  Note that each `git push` has to re-send the whole content of the git
  repository when using this option.

* `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 unncessary gpg
passphrase prompts, but it does publish the gpg keyids that can decrypt the
repository. Unset it if you need to obscure that.