more about gnupg, and .gitsecret contents. whitespace changes.

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,22 @@ 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 versions of gpg that you know to interoperate well.
+
+There is specifically between gpg version 2.1.20 and later versions
+which can an issues reading and writing keyring files between systems 
+(this shows in errors like 'gpg: skipped packet of type 12 in keybox').
+
 The git-secret internal data is separated into two directories:
 
 ### `.gitsecret/paths`