diff --git a/man/git-crypt.xml b/man/git-crypt.xml new file mode 100644 index 0000000..a444368 --- /dev/null +++ b/man/git-crypt.xml @@ -0,0 +1,493 @@ + + + + + git-crypt + 2015-05-17 + git-crypt 0.4.3 + + + Andrew Ayer + + agwa@andrewayer.name + https://www.agwa.name + + + + + git-crypt + 1 + + + + git-crypt + transparent file encryption in Git + + + + + git-crypt OPTIONS COMMAND ARGS + + + + + Common commands + + git-crypt init + + + git-crypt status + + + git-crypt lock + + + + GPG commands + + git-crypt add-gpg-user GPG_USER_ID + + + git-crypt unlock + + + + Symmetric key commands + + git-crypt export-key OUTPUT_KEY_FILE + + + git-crypt unlock KEY_FILE + + + + + Description + + + 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. + + + + + Commands + + + 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. + + + + + + + + Generate a key and prepare the current Git repository to use git-crypt. + + + + The following options are understood: + + + + KEY_NAME + KEY_NAME + + + + 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. + + + + + + + + + + + + Display a list of files in the repository, with their status (encrypted or unencrypted). + + + + The following options are understood: + + + + + + + + Show only encrypted files. + + + + + + + + + Show only unencrypted files. + + + + + + + + + + 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.) + + + + + + + + + + + + Add the users with the given GPG user IDs as collaborators. Specifically, + git-crypt uses gpg1 + 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. + + + + 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 gpg1 + man page). + + + + The following options are understood: + + + + KEY_NAME + KEY_NAME + + + + Grant access to the given key, rather than the default key. + + + + + + + + + + Don't automatically commit the changes to the .git-crypt + directory. + + + + + + + + + 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. + + + 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 + option in ~/.gnupg/gpg.conf (see + gpg1), + or use the option to add-gpg-user + on a case-by-case basis. + + + + + + + + + + + + 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's .git-crypt directory. + + + + This command takes no options. + + + + + + + + + Export the repository's shared symmetric key to the given file. + + + + The following options are understood: + + + + KEY_NAME + KEY_NAME + + + + Export the given key, rather than the default key. + + + + + + + + + + + + Display help for the given COMMAND, + or an overview of all commands if no command is specified. + + + + + + + + + Print the currently-installed version of git-crypt. + The format of the output is always "git-crypt", followed by a space, + followed by the dotted version number. + + + + + + + + + Using git-crypt + + + First, you prepare a repository to use git-crypt by running git-crypt init. + + + + Then, you specify the files to encrypt by creating a + gitattributes5 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 + + + The .gitattributes file is documented in + gitattributes5. + The file pattern format is the same as the one used by .gitignore, + as documented in gitignore5, + 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. + + + + + Multiple Key Support + + + 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. + + + + + + + + + + + + See Also + + git1, + gitattributes5, + git-crypt home page, + GitHub repository + + + +