1Changes to be aware of for git-crypt 0.4
2========================================
3
4(For a complete list of changes, see the [NEWS](NEWS.md) file.)
5
6
7### New workflow
8
9The commands for setting up a repository have changed in git-crypt 0.4.
10The previous commands continue to work, but will be removed in a future
11release of git-crypt.  Please get in the habit of using the new syntax:
12
13`git-crypt init` no longer takes an argument, and is now used only when
14initializing a repository for the very first time.  It generates a key
15and stores it in the `.git` directory. There is no longer a separate
16`keygen` step, and you no longer need to keep a copy of the key outside
17the repository.
18
19`git-crypt init` is no longer used to decrypt a cloned repository.  Instead,
20run `git-crypt unlock /path/to/keyfile`, where `keyfile` is obtained by
21running `git-crypt export-key /path/to/keyfile` from an already-decrypted
22repository.
23
24
25### GPG mode
26
27git-crypt now supports GPG.  A repository can be shared with one or more
28GPG users in lieu of sharing a secret symmetric key.  Symmetric key support
29isn't going away, but the workflow of GPG mode is extremely easy and all users
30are encouraged to consider it for their repositories.
31
32See the [README](README.md) for details on using GPG.
33
34
35### Status command
36
37A new command, `git-crypt status`, lists encrypted files, which is
38useful for making sure your `.gitattributes` pattern is protecting the
39right files.
40
41
42### Multiple key support
43
44git-crypt now lets you encrypt different sets of files with different
45keys, which is useful if you want to grant different collaborators access
46to different sets of files.
47
48See [doc/multiple_keys.md](doc/multiple_keys.md) for details.
49
50
51### Compatibility with old repositories
52
53Repositories created with older versions of git-crypt continue to work
54without any changes needed, and backwards compatibility with these
55repositories will be maintained indefinitely.
56
57However, you will not be able to take advantage of git-crypt's new
58features, such as GPG support, unless you migrate your repository.
59
60To migrate your repository, first ensure the working tree is clean.
61Then migrate your current key file and use the migrated key to unlock
62your repository as follows:
63
64    git-crypt migrate-key /path/to/old_key /path/to/migrated_key
65    git-crypt unlock /path/to/migrated_key
66
67Once you've confirmed that your repository is functional, you can delete
68both the old and migrated key files (though keeping a backup of your key
69is always a good idea).
70
71
72### Known issues
73
74It is not yet possible to revoke access from a GPG user.  This will
75require substantial development work and will be a major focus of future
76git-crypt development.
77
78The output of `git-crypt status` is currently very bare-bones and will
79be substantially improved in a future release.  Do not rely on its output
80being stable.  A future release of git-crypt will provide an option for stable
81machine-readable output.
82
83On Windows, git-crypt does not create key files with restrictive
84permissions.  Take care when using git-crypt on a multi-user Windows system.
85