git‐annex−shell − Restricted login shell for git‐annex only
SSH access

git‐annex−shell [−c] command [params ...]

git‐annex−shell is a restricted shell, similar to git−shell,
which can be used as a login shell for SSH accounts.

     Since its syntax is identical to git−shell’s, it can be
used as a drop−in replacement anywhere git−shell is used.
For example it can be used as a user’s restricted login

Any command not listed below is passed through to git−shell.

     Note that the directory parameter should be an absolute
path, otherwise it is assumed to be relative to the user’s
home directory. Also the first "/~/" or "/~user/" is
expanded to the specified home directory.

configlist directory
     This outputs a subset of the git configuration, in the
     same form as git config −−list. This is used to get the
     annex.uuid of the remote repository.

     When run in a repository that does not yet have an
     annex.uuid, one will be created, as long as a git‐annex
     branch has already been pushed to the repository, or if
     the autoinit= flag is used to indicate initialization
     is desired.

inannex directory [key ...]
     This checks if all specified keys are present in the
     annex, and exits zero if so.

     Exits 1 if the key is certainly not present in the
     annex.  Exits 100 if it’s unable to tell (perhaps the
     key is in the process of being removed from the annex).

lockcontent directory key
     This locks a key’s content in place in the annex,
     preventing it from being dropped.

     Once the content is successfully locked, outputs "OK".
     Then the content remains locked until a newline is
     received from the caller or the connection is broken.


     Exits nonzero if the content is not present, or could
     not be locked.

dropkey directory [key ...]
     This drops the annexed data for the specified keys.

recvkey directory key
     This runs rsync in server mode to receive the content
     of a key, and stores the content in the annex.

sendkey directory key
     This runs rsync in server mode to transfer out the
     content of a key.

transferinfo directory key
     This is typically run at the same time as sendkey is
     sending a key to the remote. Using it is optional, but
     is used to update progress information for the transfer
     of the key.

     It reads lines from standard input, each giving the
     number of bytes that have been received so far.

commit directory
     This commits any staged changes to the git‐annex
     branch.  It also runs the annex−content hook.

notifychanges directory
     This is used by git‐annex remotedaemon to be notified
     when refs in the remote repository are changed.

gcryptsetup directory gcryptid
     Sets up a repository as a gcrypt repository.

p2pstdio directory uuid
     This causes git‐annex−shell to communicate using the
     git‐annex p2p protocol over stdio. When supported by
     git‐annex−shell, this allows multiple actions to be run
     over a single connection, improving speed.

     The uuid is the one belonging to the repository that
     will be communicating with git‐annex−shell.


Most options are the same as in git‐annex. The ones specific
to git‐annex−shell are:

     git‐annex uses this to specify the UUID of the
     repository it was expecting git‐annex−shell to access,
     as a sanity check.

−− fields=val fields=val.. −−
     Additional fields may be specified this way, to retain
     compatibility with past versions of git‐annex−shell
     (that ignore these, but would choke on new dashed

     Currently used fields include remoteuuid=,
     associatedfile=, unlocked=, direct=, and autoinit=

After content is received or dropped from the repository by
git‐annex−shell, it runs a hook, .git/hooks/annex−content
(or hooks/annex−content on a bare repository). The hook is
not currently passed any information about what changed.


     If set, disallows any action that could modify the git‐
     annex repository.

     Note that this does not prevent passing commands on to
     git−shell.  For that, you also need ...

     If set, disallows running git−shell to handle unknown

     If set, allows data to be written to the git‐annex
     repository, but does not allow data to be removed from

     Note that this does not prevent passing commands on to
     git−shell, so you will have to separately configure git
     to reject pushes that overwrite branches or are
     otherwise not appends. The git pre−receive hook may be
     useful for accomplishing this.


     It’s a good idea to enable annex.securehashesonly in a
     repository that’s set up this way.

     If set, git‐annex−shell will refuse to run commands
     that do not operate on the specified directory.

To make a ~/.ssh/authorized_keys file that only allows git‐
annex−shell to be run, and not other commands, pass the
original command to the −c option:

      command="git‐annex−shell −c
ssh−rsa AAAAB3NzaC1y[...]

     To further restrict git‐annex−shell to a particular
repository, and fully lock it down to read−only mode:

git‐annex−shell −c \"$SSH_ORIGINAL_COMMAND\"",restrict
ssh−rsa AAAAB3NzaC1y[...]

     Obviously, ssh−rsa AAAAB3NzaC1y[...]
needs to replaced with your SSH key. The above also assumes
git‐annex−shell is available in your $PATH, use an absolute
path if it is not the case. Also note how the above uses the
restrict option instead of an explicit list of functionality
to disallow. This only works in certain OpenSSH releases,
starting from 7.1p2.

     To only allow adding new objects to the repository, the
GIT_ANNEX_SHELL_APPENDONLY variable can be used as well:

GIT_ANNEX_SHELL_APPENDONLY=true git‐annex−shell −c
\"$SSH_ORIGINAL_COMMAND\"",restrict ssh−rsa

     This will not keep an attacker from destroying the git
history, as explained above. For this you might want to
disallow certain operations, like branch deletion and
force−push, with options from git−config(1). For example:

     git config receive.denyDeletes true git config
receive.denyNonFastForwards true

     With this configuration, git commits can still remove
files, but they will still be available in the git history
and git‐annex will retain their contents. Changes to git‐
annex branch, however, can negatively impact git‐annex’s
location tracking information and might cause data loss. To


work around this problem, more complex hooks are required,
see for example the update−paranoid hook in the git source



Joey Hess <>