GIT-CRYPT(1) | git-crypt | GIT-CRYPT(1) |
git-crypt - transparent file encryption in Git
git-crypt [OPTIONS] COMMAND [ARGS...]
git-crypt init
git-crypt status
git-crypt lock
git-crypt add-gpg-user GPG_USER_ID
git-crypt unlock
git-crypt export-key OUTPUT_KEY_FILE
git-crypt unlock KEY_FILE
git-crypt 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.
git-crypt 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 after the name of the sub-command.
init [OPTIONS]
The following options are understood:
-k KEY_NAME, --key-name KEY_NAME
status [OPTIONS]
The following options are understood:
-e
-u
-f, --fix
add-gpg-user [OPTIONS] GPG_USER_ID...
GPG_USER_ID 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 gpg(1) man page).
The following options are understood:
-k KEY_NAME, --key-name KEY_NAME
-n, --no-commit
--trusted
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.
If you don't want to use the Web of Trust, you can either change GPG's trust model by setting the trust-model option in ~/.gnupg/gpg.conf (see gpg(1)), or use the --trusted option to add-gpg-user on a case-by-case basis.
unlock [KEY_FILE...]
This command takes no options.
export-key [OPTIONS] FILENAME
The following options are understood:
-k KEY_NAME, --key-name KEY_NAME
help [COMMAND]
version
First, you prepare a repository to use git-crypt by running git-crypt init.
Then, you specify the files to encrypt by creating a gitattributes(5) file. Each file which you want to encrypt should be assigned the "filter=git-crypt diff=git-crypt" attributes. For example:
secretfile filter=git-crypt diff=git-crypt *.key filter=git-crypt diff=git-crypt
Like a .gitignore file, .gitattributes files can match wildcards and should be checked into the repository. Make sure you don't accidentally encrypt the .gitattributes file itself (or other git files like .gitignore or .gitmodules). Make sure your .gitattributes rules are in place before you add sensitive files, or those files won't be encrypted!
To share the repository with others (or with yourself) using GPG, run:
git-crypt add-gpg-user GPG_USER_ID
GPG_USER_ID can be a key ID, a full fingerprint, an email address, or anything else that uniquely identifies a public key to GPG. Note: git-crypt add-gpg-user will add and commit a GPG-encrypted key file in the .git-crypt directory of the root of your repository.
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):
git-crypt export-key /path/to/key
After cloning a repository with encrypted files, unlock with with GPG:
git-crypt unlock
Or with a symmetric key:
git-crypt unlock /path/to/key
That's all you need to do - after git-crypt is set up (either with git-crypt init or git-crypt unlock), you can use git normally - encryption and decryption happen transparently.
The .gitattributes file is documented in gitattributes(5). The file pattern format is the same as the one used by .gitignore, as documented in gitignore(5), with the exception that specifying merely a directory (e.g. "/dir/") is not sufficient to encrypt all files beneath it.
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:
* filter=git-crypt diff=git-crypt .gitattributes !filter !diff
The second pattern is essential for ensuring that .gitattributes itself is not encrypted.
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.
To generate an alternative key named KEYNAME, pass the -k KEYNAME option to git-crypt init as follows:
git-crypt init -k KEYNAME
To encrypt a file with an alternative key, use the git-crypt-KEYNAME filter in .gitattributes as follows:
secretfile filter=git-crypt-KEYNAME diff=git-crypt-KEYNAME
To export an alternative key or share it with a GPG user, pass the -k KEYNAME option to git-crypt export-key or git-crypt add-gpg-user as follows:
git-crypt export-key -k KEYNAME /path/to/keyfile git-crypt add-gpg-user -k KEYNAME GPG_USER_ID
To unlock a repository with an alternative key, use git-crypt unlock normally. git-crypt will automatically determine which key is being used.
git(1), gitattributes(5), git-crypt home page[1], GitHub repository[2]
Andrew Ayer <agwa@andrewayer.name>
2022-04-21 | git-crypt 0.7.0 |