mirror of
https://github.com/AGWA/git-crypt.git
synced 2025-12-05 20:40:05 -08:00
494 lines
16 KiB
XML
494 lines
16 KiB
XML
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<refentry>
|
|
<!--
|
|
Copyright (c) 2015 Andrew Ayer
|
|
|
|
See COPYING file for license information.
|
|
-->
|
|
<refentryinfo>
|
|
<title>git-crypt</title>
|
|
<date>2022-04-21</date>
|
|
<productname>git-crypt 0.8.0</productname>
|
|
|
|
<author>
|
|
<othername>Andrew Ayer</othername>
|
|
<contrib></contrib>
|
|
<email>agwa@andrewayer.name</email>
|
|
<uri>https://www.agwa.name</uri>
|
|
</author>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>git-crypt</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>git-crypt</refname>
|
|
<refpurpose>transparent file encryption in Git</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>git-crypt <arg choice="opt"><replaceable>OPTIONS</replaceable></arg> <arg choice="plain"><replaceable>COMMAND</replaceable></arg> <arg choice="opt" rep="repeat"><replaceable>ARGS</replaceable></arg></command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Common commands</title>
|
|
<cmdsynopsis>
|
|
<command>git-crypt init</command>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>git-crypt status</command>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>git-crypt lock</command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsynopsisdiv>
|
|
<title>GPG commands</title>
|
|
<cmdsynopsis>
|
|
<command>git-crypt add-gpg-user <arg choice="plain"><replaceable>GPG_USER_ID</replaceable></arg></command>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>git-crypt unlock</command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsynopsisdiv>
|
|
<title>Symmetric key commands</title>
|
|
<cmdsynopsis>
|
|
<command>git-crypt export-key <arg choice="plain"><replaceable>OUTPUT_KEY_FILE</replaceable></arg></command>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>git-crypt unlock <arg choice="plain"><replaceable>KEY_FILE</replaceable></arg></command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>git-crypt</command> 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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Commands</title>
|
|
|
|
<para>
|
|
<command>git-crypt</command> 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 <emphasis>after</emphasis> the name of the sub-command.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>init <arg choice="opt"><replaceable>OPTIONS</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
Generate a key and prepare the current Git repository to use git-crypt.
|
|
</para>
|
|
|
|
<para>
|
|
The following options are understood:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-k</option> <replaceable>KEY_NAME</replaceable></term>
|
|
<term><option>--key-name</option> <replaceable>KEY_NAME</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>status <arg choice="opt"><replaceable>OPTIONS</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
Display a list of files in the repository, with their status (encrypted or unencrypted).
|
|
</para>
|
|
|
|
<para>
|
|
The following options are understood:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-e</option></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Show only encrypted files.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-u</option></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Show only unencrypted files.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-f</option></term>
|
|
<term><option>--fix</option></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
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.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>add-gpg-user <arg choice="opt"><replaceable>OPTIONS</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>GPG_USER_ID</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
Add the users with the given GPG user IDs as collaborators. Specifically,
|
|
git-crypt uses <citerefentry><refentrytitle>gpg</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
to encrypt the shared symmetric key
|
|
to the public keys of each GPG user ID, and stores the GPG-encrypted
|
|
keys in the <filename>.git-crypt</filename> directory at the root of the repository.
|
|
</para>
|
|
|
|
<para>
|
|
<replaceable>GPG_USER_ID</replaceable> 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 <citerefentry><refentrytitle>gpg</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
man page).
|
|
</para>
|
|
|
|
<para>
|
|
The following options are understood:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-k</option> <replaceable>KEY_NAME</replaceable></term>
|
|
<term><option>--key-name</option> <replaceable>KEY_NAME</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Grant access to the given key, rather than the default key.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--no-commit</option></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Don't automatically commit the changes to the <filename>.git-crypt</filename>
|
|
directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--trusted</option></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
If you don't want to use the Web of Trust, you can either change
|
|
GPG's trust model by setting the <option>trust-model</option>
|
|
option in <filename>~/.gnupg/gpg.conf</filename> (see
|
|
<citerefentry><refentrytitle>gpg</refentrytitle><manvolnum>1</manvolnum></citerefentry>),
|
|
or use the <option>--trusted</option> option to <command>add-gpg-user</command>
|
|
on a case-by-case basis.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>unlock <!--<arg choice="opt"><replaceable>OPTIONS</replaceable></arg> --><arg choice="opt" rep="repeat"><replaceable>KEY_FILE</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
This command takes no options.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>export-key <arg choice="opt"><replaceable>OPTIONS</replaceable></arg> <arg choice="plain"><replaceable>FILENAME</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
Export the repository's shared symmetric key to the given file.
|
|
</para>
|
|
|
|
<para>
|
|
The following options are understood:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-k</option> <replaceable>KEY_NAME</replaceable></term>
|
|
<term><option>--key-name</option> <replaceable>KEY_NAME</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Export the given key, rather than the default key.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>help <arg choice="opt"><replaceable>COMMAND</replaceable></arg></option></term>
|
|
<listitem>
|
|
<para>
|
|
Display help for the given <arg choice="plain"><replaceable>COMMAND</replaceable></arg>,
|
|
or an overview of all commands if no command is specified.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print the currently-installed version of <command>git-crypt</command>.
|
|
The format of the output is always "git-crypt", followed by a space,
|
|
followed by the dotted version number.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Using git-crypt</title>
|
|
|
|
<para>
|
|
First, you prepare a repository to use git-crypt by running <command>git-crypt init</command>.
|
|
</para>
|
|
|
|
<para>
|
|
Then, you specify the files to encrypt by creating a
|
|
<citerefentry><refentrytitle>gitattributes</refentrytitle><manvolnum>5</manvolnum></citerefentry> file.
|
|
Each file which you want to encrypt should be assigned the "<literal>filter=git-crypt diff=git-crypt</literal>"
|
|
attributes. For example:
|
|
</para>
|
|
|
|
<screen>secretfile filter=git-crypt diff=git-crypt *.key filter=git-crypt diff=git-crypt</screen>
|
|
|
|
<para>
|
|
Like a <filename>.gitignore</filename> file, <filename>.gitattributes</filename> files can match wildcards and
|
|
should be checked into the repository. Make sure you don't accidentally encrypt the
|
|
<filename>.gitattributes</filename> file itself (or other git files like <filename>.gitignore</filename>
|
|
or <filename>.gitmodules</filename>). Make sure your <filename>.gitattributes</filename> rules
|
|
are in place <emphasis>before</emphasis> you add sensitive files, or those files won't be encrypted!
|
|
</para>
|
|
|
|
<para>
|
|
To share the repository with others (or with yourself) using GPG, run:
|
|
</para>
|
|
|
|
<screen>git-crypt add-gpg-user <replaceable>GPG_USER_ID</replaceable></screen>
|
|
|
|
<para>
|
|
<replaceable>GPG_USER_ID</replaceable> can be a key ID, a full fingerprint, an email address, or anything
|
|
else that uniquely identifies a public key to GPG. Note: <command>git-crypt add-gpg-user</command> will
|
|
add and commit a GPG-encrypted key file in the <filename>.git-crypt</filename> directory of
|
|
the root of your repository.
|
|
</para>
|
|
|
|
<para>
|
|
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):
|
|
</para>
|
|
|
|
<screen>git-crypt export-key <replaceable>/path/to/key</replaceable></screen>
|
|
|
|
<para>
|
|
After cloning a repository with encrypted files, unlock with with GPG:
|
|
</para>
|
|
|
|
<screen>git-crypt unlock</screen>
|
|
|
|
<para>
|
|
Or with a symmetric key:
|
|
</para>
|
|
|
|
<screen>git-crypt unlock /path/to/key</screen>
|
|
|
|
<para>
|
|
That's all you need to do - after git-crypt is set up (either with
|
|
<command>git-crypt init</command> or <command>git-crypt unlock</command>),
|
|
you can use git normally - encryption and decryption happen transparently.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>The .gitattributes file</title>
|
|
|
|
<para>
|
|
The <filename>.gitattributes</filename> file is documented in
|
|
<citerefentry><refentrytitle>gitattributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
|
The file pattern format is the same as the one used by <filename>.gitignore</filename>,
|
|
as documented in <citerefentry><refentrytitle>gitignore</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
|
with the exception that specifying merely a directory (e.g. "<literal>/dir/</literal>")
|
|
is <emphasis>not</emphasis> sufficient to encrypt all files beneath it.
|
|
</para>
|
|
|
|
<para>
|
|
Also note that the pattern "<literal>dir/*</literal>" does not match files under
|
|
sub-directories of dir/. To encrypt an entire sub-tree dir/, place the
|
|
following in <filename>dir/.gitattributes</filename>:
|
|
</para>
|
|
|
|
<screen>* filter=git-crypt diff=git-crypt .gitattributes !filter !diff</screen>
|
|
|
|
<para>
|
|
The second pattern is essential for ensuring that <filename>.gitattributes</filename> itself
|
|
is not encrypted.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Multiple Key Support</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
To generate an alternative key named <replaceable>KEYNAME</replaceable>,
|
|
pass the <command>-k <replaceable>KEYNAME</replaceable></command>
|
|
option to <command>git-crypt init</command> as follows:
|
|
</para>
|
|
|
|
<screen>git-crypt init -k <replaceable>KEYNAME</replaceable></screen>
|
|
|
|
<para>
|
|
To encrypt a file with an alternative key, use the <literal>git-crypt-<replaceable>KEYNAME</replaceable></literal>
|
|
filter in <filename>.gitattributes</filename> as follows:
|
|
</para>
|
|
|
|
<screen><replaceable>secretfile</replaceable> filter=git-crypt-<replaceable>KEYNAME</replaceable> diff=git-crypt-<replaceable>KEYNAME</replaceable></screen>
|
|
|
|
<para>
|
|
To export an alternative key or share it with a GPG user, pass the
|
|
<command>-k <replaceable>KEYNAME</replaceable></command> option to
|
|
<command>git-crypt export-key</command> or <command>git-crypt add-gpg-user</command>
|
|
as follows:
|
|
</para>
|
|
|
|
<screen>git-crypt export-key -k <replaceable>KEYNAME</replaceable> <filename><replaceable>/path/to/keyfile</replaceable></filename> git-crypt add-gpg-user -k <replaceable>KEYNAME</replaceable> <replaceable>GPG_USER_ID</replaceable></screen>
|
|
|
|
<para>
|
|
To unlock a repository with an alternative key, use <command>git-crypt unlock</command>
|
|
normally. git-crypt will automatically determine which key is being used.
|
|
</para>
|
|
</refsect1>
|
|
<!--
|
|
<refsect1>
|
|
<title>Global options</title>
|
|
|
|
<para>
|
|
The following options are understood by <command>git-crypt</command> and can
|
|
be used with any sub-command. Since they apply globally
|
|
to <command>git-crypt</command>, they must be specified on the command line
|
|
<emphasis>before</emphasis> the sub-command name.
|
|
</para>
|
|
<variablelist>
|
|
</variablelist>
|
|
</refsect1>
|
|
-->
|
|
|
|
<!--
|
|
<refsect1>
|
|
<title>Files</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>/path/to/file</filename></term>
|
|
<listitem><para>Description.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
-->
|
|
|
|
<!--
|
|
<refsect1>
|
|
<title>Environment Variables</title>
|
|
|
|
<variablelist class='environment-variables'>
|
|
<varlistentry>
|
|
<term><varname>NAME</varname></term>
|
|
<listitem>
|
|
<para>Description.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
-->
|
|
|
|
<!-- TODO: examples section
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>Hello world?</para>
|
|
</refsect1>
|
|
-->
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>git</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>gitattributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
|
<ulink url="https://www.agwa.name/projects/git-crypt">git-crypt home page</ulink>,
|
|
<ulink url="https://github.com/AGWA/git-crypt">GitHub repository</ulink>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|