'\" t
.\"     Title: git-crypt
.\"    Author: Andrew Ayer <agwa@andrewayer.name>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2022-04-21
.\"    Manual: git-crypt
.\"    Source: git-crypt 0.7.0
.\"  Language: English
.\"
.TH "GIT\-CRYPT" "1" "2022\-04\-21" "git-crypt 0.7.0" "git-crypt"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-crypt \- transparent file encryption in Git
.SH "SYNOPSIS"
.HP \w'\fBgit\-crypt\ \fR\fB[\fIOPTIONS\fR]\fR\fB\ \fR\fB\fICOMMAND\fR\fR\fB\ \fR\fB[\fIARGS\fR...]\fR\ 'u
\fBgit\-crypt \fR\fB[\fIOPTIONS\fR]\fR\fB \fR\fB\fICOMMAND\fR\fR\fB \fR\fB[\fIARGS\fR...]\fR
.SH "COMMON COMMANDS"
.HP \w'\fBgit\-crypt\ init\fR\ 'u
\fBgit\-crypt init\fR
.HP \w'\fBgit\-crypt\ status\fR\ 'u
\fBgit\-crypt status\fR
.HP \w'\fBgit\-crypt\ lock\fR\ 'u
\fBgit\-crypt lock\fR
.SH "GPG COMMANDS"
.HP \w'\fBgit\-crypt\ add\-gpg\-user\ \fR\fB\fIGPG_USER_ID\fR\fR\ 'u
\fBgit\-crypt add\-gpg\-user \fR\fB\fIGPG_USER_ID\fR\fR
.HP \w'\fBgit\-crypt\ unlock\fR\ 'u
\fBgit\-crypt unlock\fR
.SH "SYMMETRIC KEY COMMANDS"
.HP \w'\fBgit\-crypt\ export\-key\ \fR\fB\fIOUTPUT_KEY_FILE\fR\fR\ 'u
\fBgit\-crypt export\-key \fR\fB\fIOUTPUT_KEY_FILE\fR\fR
.HP \w'\fBgit\-crypt\ unlock\ \fR\fB\fIKEY_FILE\fR\fR\ 'u
\fBgit\-crypt unlock \fR\fB\fIKEY_FILE\fR\fR
.SH "DESCRIPTION"
.PP
\fBgit\-crypt\fR
enables transparent encryption and decryption of files in a git repository\&. Files which you choose to protect are encrypted when committed, and decrypted when checked out\&. git\-crypt lets you freely share a repository containing a mix of public and private content\&. git\-crypt gracefully degrades, so developers without the secret key can still clone and commit to a repository with encrypted files\&. This lets you store your secret material (such as keys or passwords) in the same repository as your code, without requiring you to lock down your entire repository\&.
.SH "COMMANDS"
.PP
\fBgit\-crypt\fR
is logically divided into several sub\-commands which perform distinct tasks\&. Each sub\-command, and its arguments, are documented below\&. Note that arguments and options to sub\-commands must be specified on the command line
\fIafter\fR
the name of the sub\-command\&.
.PP
\fBinit \fR\fB[\fIOPTIONS\fR]\fR
.RS 4
Generate a key and prepare the current Git repository to use git\-crypt\&.
.sp
The following options are understood:
.PP
\fB\-k\fR \fIKEY_NAME\fR, \fB\-\-key\-name\fR \fIKEY_NAME\fR
.RS 4
Initialize the given key instead of the default key\&. git\-crypt supports multiple keys per repository, allowing you to share different files with different sets of collaborators\&.
.RE
.RE
.PP
\fBstatus \fR\fB[\fIOPTIONS\fR]\fR
.RS 4
Display a list of files in the repository, with their status (encrypted or unencrypted)\&.
.sp
The following options are understood:
.PP
\fB\-e\fR
.RS 4
Show only encrypted files\&.
.RE
.PP
\fB\-u\fR
.RS 4
Show only unencrypted files\&.
.RE
.PP
\fB\-f\fR, \fB\-\-fix\fR
.RS 4
Encrypt files that should be encrypted but were committed to the repository or added to the index without encryption\&. (This can happen if a file is added before git\-crypt is initialized or before the file is added to the gitattributes file\&.)
.RE
.RE
.PP
\fBadd\-gpg\-user \fR\fB[\fIOPTIONS\fR]\fR\fB \fR\fB\fIGPG_USER_ID\fR...\fR
.RS 4
Add the users with the given GPG user IDs as collaborators\&. Specifically, git\-crypt uses
\fBgpg\fR(1)
to encrypt the shared symmetric key to the public keys of each GPG user ID, and stores the GPG\-encrypted keys in the
\&.git\-crypt
directory at the root of the repository\&.
.sp
\fIGPG_USER_ID\fR
can be a key ID, a full fingerprint, an email address, or anything else that uniquely identifies a public key to GPG (see "HOW TO SPECIFY A USER ID" in the
\fBgpg\fR(1)
man page)\&.
.sp
The following options are understood:
.PP
\fB\-k\fR \fIKEY_NAME\fR, \fB\-\-key\-name\fR \fIKEY_NAME\fR
.RS 4
Grant access to the given key, rather than the default key\&.
.RE
.PP
\fB\-n\fR, \fB\-\-no\-commit\fR
.RS 4
Don\*(Aqt automatically commit the changes to the
\&.git\-crypt
directory\&.
.RE
.PP
\fB\-\-trusted\fR
.RS 4
Assume that the GPG keys specified on the command line are trusted; i\&.e\&. they actually belong to the users that they claim to belong to\&.
.sp
Without this option, git\-crypt uses the same trust model as GPG, which is based on the Web of Trust by default\&. Under this model, git\-crypt will reject GPG keys that do not have trusted signatures\&.
.sp
If you don\*(Aqt want to use the Web of Trust, you can either change GPG\*(Aqs trust model by setting the
\fBtrust\-model\fR
option in
~/\&.gnupg/gpg\&.conf
(see
\fBgpg\fR(1)), or use the
\fB\-\-trusted\fR
option to
\fBadd\-gpg\-user\fR
on a case\-by\-case basis\&.
.RE
.RE
.PP
\fBunlock \fR\fB\fR\fB[\fIKEY_FILE\fR...]\fR
.RS 4
Decrypt the repository\&. If one or more key files are specified on the command line, git\-crypt attempts to decrypt using those shared symmetric keys\&. If no key files are specified, git\-crypt attempts to decrypt using a GPG\-encrypted key stored in the repository\*(Aqs \&.git\-crypt directory\&.
.sp
This command takes no options\&.
.RE
.PP
\fBexport\-key \fR\fB[\fIOPTIONS\fR]\fR\fB \fR\fB\fIFILENAME\fR\fR
.RS 4
Export the repository\*(Aqs shared symmetric key to the given file\&.
.sp
The following options are understood:
.PP
\fB\-k\fR \fIKEY_NAME\fR, \fB\-\-key\-name\fR \fIKEY_NAME\fR
.RS 4
Export the given key, rather than the default key\&.
.RE
.RE
.PP
\fBhelp \fR\fB[\fICOMMAND\fR]\fR
.RS 4
Display help for the given
\fICOMMAND\fR, or an overview of all commands if no command is specified\&.
.RE
.PP
\fBversion\fR
.RS 4
Print the currently\-installed version of
\fBgit\-crypt\fR\&. The format of the output is always "git\-crypt", followed by a space, followed by the dotted version number\&.
.RE
.SH "USING GIT\-CRYPT"
.PP
First, you prepare a repository to use git\-crypt by running
\fBgit\-crypt init\fR\&.
.PP
Then, you specify the files to encrypt by creating a
\fBgitattributes\fR(5)
file\&. Each file which you want to encrypt should be assigned the "filter=git\-crypt diff=git\-crypt" attributes\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
secretfile filter=git\-crypt diff=git\-crypt
*\&.key filter=git\-crypt diff=git\-crypt
.fi
.if n \{\
.RE
.\}
.PP
Like a
\&.gitignore
file,
\&.gitattributes
files can match wildcards and should be checked into the repository\&. Make sure you don\*(Aqt accidentally encrypt the
\&.gitattributes
file itself (or other git files like
\&.gitignore
or
\&.gitmodules)\&. Make sure your
\&.gitattributes
rules are in place
\fIbefore\fR
you add sensitive files, or those files won\*(Aqt be encrypted!
.PP
To share the repository with others (or with yourself) using GPG, run:
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt add\-gpg\-user \fIGPG_USER_ID\fR
.fi
.if n \{\
.RE
.\}
.PP
\fIGPG_USER_ID\fR
can be a key ID, a full fingerprint, an email address, or anything else that uniquely identifies a public key to GPG\&. Note:
\fBgit\-crypt add\-gpg\-user\fR
will add and commit a GPG\-encrypted key file in the
\&.git\-crypt
directory of the root of your repository\&.
.PP
Alternatively, you can export a symmetric secret key, which you must securely convey to collaborators (GPG is not required, and no files are added to your repository):
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt export\-key \fI/path/to/key\fR
.fi
.if n \{\
.RE
.\}
.PP
After cloning a repository with encrypted files, unlock with with GPG:
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt unlock
.fi
.if n \{\
.RE
.\}
.PP
Or with a symmetric key:
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt unlock /path/to/key
.fi
.if n \{\
.RE
.\}
.PP
That\*(Aqs all you need to do \- after git\-crypt is set up (either with
\fBgit\-crypt init\fR
or
\fBgit\-crypt unlock\fR), you can use git normally \- encryption and decryption happen transparently\&.
.SH "THE \&.GITATTRIBUTES FILE"
.PP
The
\&.gitattributes
file is documented in
\fBgitattributes\fR(5)\&. The file pattern format is the same as the one used by
\&.gitignore, as documented in
\fBgitignore\fR(5), with the exception that specifying merely a directory (e\&.g\&. "/dir/") is
\fInot\fR
sufficient to encrypt all files beneath it\&.
.PP
Also note that the pattern "dir/*" does not match files under sub\-directories of dir/\&. To encrypt an entire sub\-tree dir/, place the following in
dir/\&.gitattributes:
.sp
.if n \{\
.RS 4
.\}
.nf
* filter=git\-crypt diff=git\-crypt
\&.gitattributes !filter !diff
.fi
.if n \{\
.RE
.\}
.PP
The second pattern is essential for ensuring that
\&.gitattributes
itself is not encrypted\&.
.SH "MULTIPLE KEY SUPPORT"
.PP
In addition to the implicit default key, git\-crypt supports alternative keys which can be used to encrypt specific files and can be shared with specific GPG users\&. This is useful if you want to grant different collaborators access to different sets of files\&.
.PP
To generate an alternative key named
\fIKEYNAME\fR, pass the
\fB\-k \fR\fB\fIKEYNAME\fR\fR
option to
\fBgit\-crypt init\fR
as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt init \-k \fIKEYNAME\fR
.fi
.if n \{\
.RE
.\}
.PP
To encrypt a file with an alternative key, use the
git\-crypt\-\fIKEYNAME\fR
filter in
\&.gitattributes
as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIsecretfile\fR filter=git\-crypt\-\fIKEYNAME\fR diff=git\-crypt\-\fIKEYNAME\fR
.fi
.if n \{\
.RE
.\}
.PP
To export an alternative key or share it with a GPG user, pass the
\fB\-k \fR\fB\fIKEYNAME\fR\fR
option to
\fBgit\-crypt export\-key\fR
or
\fBgit\-crypt add\-gpg\-user\fR
as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
git\-crypt export\-key \-k \fIKEYNAME\fR \fI/path/to/keyfile\fR
git\-crypt add\-gpg\-user \-k \fIKEYNAME\fR \fIGPG_USER_ID\fR
.fi
.if n \{\
.RE
.\}
.PP
To unlock a repository with an alternative key, use
\fBgit\-crypt unlock\fR
normally\&. git\-crypt will automatically determine which key is being used\&.
.SH "SEE ALSO"
.PP
\fBgit\fR(1),
\fBgitattributes\fR(5),
\m[blue]\fBgit\-crypt home page\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fBGitHub repository\fR\m[]\&\s-2\u[2]\d\s+2
.SH "AUTHOR"
.PP
\fBAndrew Ayer\fR <\&agwa@andrewayer\&.name\&>
.RS 4
.RE
.SH "NOTES"
.IP " 1." 4
git-crypt home page
.RS 4
\%https://www.agwa.name/projects/git-crypt
.RE
.IP " 2." 4
GitHub repository
.RS 4
\%https://github.com/AGWA/git-crypt
.RE