Merge branch 'master' into gpg-error-checking

man/man1/git-secret-add.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-ADD" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-ADD" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-add\fR \- starts to track added files\.

man/man1/git-secret-cat.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-CAT" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-CAT" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-cat\fR \- decrypts files passed on command line to stdout

man/man1/git-secret-changes.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-CHANGES" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-CHANGES" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-changes\fR \- view diff of the hidden files\.

man/man1/git-secret-clean.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-CLEAN" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-CLEAN" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-clean\fR \- removes all the hidden files\.

man/man1/git-secret-hide.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-HIDE" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-HIDE" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-hide\fR \- encrypts all added files with the inner keyring\.

man/man1/git-secret-init.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-INIT" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-INIT" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-init\fR \- initializes git\-secret repository\.

man/man1/git-secret-killperson.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-KILLPERSON" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-KILLPERSON" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-killperson\fR \- deletes key identified by an email from the inner keyring\.

man/man1/git-secret-list.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-LIST" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-LIST" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-list\fR \- prints all the added files\.

man/man1/git-secret-remove.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-REMOVE" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-REMOVE" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-remove\fR \- removes files from index\.

man/man1/git-secret-reveal.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-REVEAL" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-REVEAL" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-reveal\fR \- decrypts all added files\.

man/man1/git-secret-tell.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-TELL" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-TELL" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-tell\fR \- adds a person, who can access private data\.

man/man1/git-secret-usage.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-USAGE" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-USAGE" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-usage\fR \- prints all the available commands\.

man/man1/git-secret-whoknows.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET\-WHOKNOWS" "1" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET\-WHOKNOWS" "1" "May 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\-whoknows\fR \- prints email\-labels for each key in the keyring\.

man/man7/git-secret.7

@@ -1,12 +1,12 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-SECRET" "7" "April 2018" "sobolevn" "git-secret"
+.TH "GIT\-SECRET" "7" "June 2018" "sobolevn" "git-secret"
 .
 .SH "NAME"
 \fBgit\-secret\fR
 .
-.SH "Usage"
+.SH "Usage: Setting up git\-secret in a repository"
 These steps cover the basic process of using \fBgit\-secret\fR:
 .
 .IP "1." 4
@@ -35,7 +35,7 @@ Later you can decrypt files with the \fBgit secret reveal\fR command, or just sh
 .
 .IP "" 0
 .
-.SS "I want to add someone to the repository"
+.SS "Usage: Adding someone to a repository using git\-secret"
 .
 .IP "1." 4
 Get their \fBgpg\fR public\-key\. \fBYou won\'t need their secret key\.\fR
@@ -68,8 +68,17 @@ The settings available to be changed are:
 .
 .IP "" 0
 .
-.SH "Internals \-\- the <code>\.gitsecret</code> folder"
-This folder contains all the information about the data encrypted in this repo, and about which public/private key sets can access the encrypted data\. Use the various \'git secret\' commands to manipulate the files in \fB\.gitsecret\fR, you should not change the data in these files directly\.
+.SH "The <code>\.gitsecret</code> folder"
+This folder contains information about the files encrypted by git\-secret, and about which public/private key sets can access the encrypted data\.
+.
+.P
+Use the various \'git secret\' commands to manipulate the files in \fB\.gitsecret\fR, you should not change the data in these files directly\.
+.
+.P
+Exactly which files exist in the \.gitsecret folder and what their contents are vary slightly across different versions of gpg\. Thus it is best to use git\-secret with the same version of gpg being used by all users\. This can be forced using SECRETS_GPG_COMMAND environment variable\.
+.
+.P
+Specifically, there is an issue between gpg version 2\.1\.20 and later versions which can cause problems reading and writing keyring files between systems (this shows up in errors like \'gpg: skipped packet of type 12 in keybox\')\.
 .
 .P
 The git\-secret internal data is separated into two directories:

man/man7/git-secret.7.ronn

@@ -1,31 +1,40 @@
-## Usage
+## Usage: Setting up git-secret in a repository
 
 These steps cover the basic process of using `git-secret`:
 
 0. Before starting, make sure you have created `gpg` RSA key-pair: public and secret key identified by your email address.
+
 1. Begin with an existing or new git repository. You'll use the 'git secret' commands to add the keyrings and information 
 to make the git-secret hide and reveal files in this repository.
+
 2. Initialize the `git-secret` repository by running `git secret init` command. the `.gitsecret/` folder will be created, 
 **Note** all the contents of the `.gitsecret/` folder should be checked in, /except/ the `random_seed` file. 
 In other words, of the files in .gitsecret, only the random_seed file should be mentioned in your .gitignore file.
+
 3. Add the first user to the git-secret repo keyring by running `git secret tell your@gpg.email`.
+
 4. Now it's time to add files you wish to encrypt inside the `git-secret` repository. 
 It can be done by running `git secret add <filenames...>` command. Make sure these files are ignored by mentions in 
 .gitignore, otherwise `git-secret` won't allow you to add them, as these files could be stored unencrypted.
+
 5. When done, run `git secret hide` to encrypt all files which you have added by the `git secret add` command.  
 The data will be encrypted with the public-keys described by the `git secret tell` command. 
 After using `git secret hide` to encrypt your data, it is safe to commit your changes. 
 **NOTE:**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
+
 6. Later you can decrypt files with the `git secret reveal` command, or just show their contents to stdout with the 
 `git secret cat` command. If you used a password on your GPG key (always recommended), it will ask you for your password. 
 And you're done!
 
-### I want to add someone to the repository
+### Usage: Adding someone to a repository using git-secret
 
 1. Get their `gpg` public-key. **You won't need their secret key.**
+
 2. Import this key into your `gpg` setup (in ~/.gnupg or similar) by running `gpg --import KEY_NAME.txt`
+
 3. Now add this person to your secrets repo by running `git secret tell persons@email.id` 
 (this will be the email address assocated with the public key)
+
 4. The newly added user cannot yet read the encrypted files. Now, re-encrypt the files using 
 `git secret reveal; git secret hide -d`, and then commit and push the newly encrypted files. 
 (The -d options deletes the unencrypted file after re-encrypting it). 
@@ -49,13 +58,23 @@ After doing so rerun the tests to be sure that it won't break anything. Tested t
 
 * `$SECRETS_EXTENSION` - sets the secret files extension, defaults to `.secret`. It can be changed to any valid file extension.
 
-## Internals -- the `.gitsecret` folder
+## The `.gitsecret` folder
 
-This folder contains all the information about the data encrypted in this repo, 
+This folder contains information about the files encrypted by git-secret, 
 and about which public/private key sets can access the encrypted data. 
+
 Use the various 'git secret' commands to manipulate the files in `.gitsecret`, 
 you should not change the data in these files directly.
 
+Exactly which files exist in the .gitsecret folder and what their contents are
+vary slightly across different versions of gpg. Thus it is best to use
+git-secret with the same version of gpg being used by all users. 
+This can be forced using SECRETS_GPG_COMMAND environment variable.
+
+Specifically, there is an issue between gpg version 2.1.20 and later versions
+which can cause problems reading and writing keyring files between systems 
+(this shows up in errors like 'gpg: skipped packet of type 12 in keybox').
+
 The git-secret internal data is separated into two directories:
 
 ### `.gitsecret/paths`