improve git-secret docs

man/man7/git-secret.7

@@ -13,18 +13,21 @@ These steps cover the basic process of using \fBgit\-secret\fR:
 Before starting, make sure you have created \fBgpg\fR RSA key\-pair: public and secret key identified by your email address\.
 .
 .IP "2." 4
-Initialize \fBgit\-secret\fR repository by running \fBgit secret init\fR command\. \fB\.gitsecret/\fR folder will be created, \fBnote\fR that \fB\.gitsecret/\fR folder with the exception of the random_seed file should \fBnot\fR ignored via inclusion in your \.gitignore file \fIhttps://github\.com/sobolevn/git\-secret/issues/39\fR\.
+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\.
 .
 .IP "3." 4
-Add first user to the system by running \fBgit secret tell your@gpg\.email\fR\.
+Initialize the \fBgit\-secret\fR repository by running \fBgit secret init\fR command\. the \fB\.gitsecret/\fR folder will be created, \fBNote\fR that the contents of the \fB\.gitsecret/\fR folder should all be checked in, with the exception of the random_seed file\. In other words, only the random_seen file should be mentioned in your \.gitignore file]
 .
 .IP "4." 4
-Now it\'s time to add files you wish to encrypt inside the \fBgit\-secret\fR repository\. It can be done by running \fBgit secret add <filenames\.\.\.>\fR command\. Make sure these files are ignored by mentions in \.gitignore, otherwise \fBgit\-secret\fR won\'t allow you to add them, as these files could be stored unencrypted\.
+Add first user to the git\-secret repo keyring by running \fBgit secret tell your@gpg\.email\fR\.
 .
 .IP "5." 4
-When done, run \fBgit secret hide\fR to encrypt all files which you have added by the \fBgit secret add\fR command\. The data will be encrypted with the public\-keys described by the \fBgit secret tell\fR command\. After using \fBgit secret hide\fR to encrypt your data, it is safe to commit your changes\. \fBNOTE:\fR\. It\'s recommended to add \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\.
+Now it\'s time to add files you wish to encrypt inside the \fBgit\-secret\fR repository\. It can be done by running \fBgit secret add <filenames\.\.\.>\fR command\. Make sure these files are ignored by mentions in \.gitignore, otherwise \fBgit\-secret\fR won\'t allow you to add them, as these files could be stored unencrypted\.
 .
 .IP "6." 4
+When done, run \fBgit secret hide\fR to encrypt all files which you have added by the \fBgit secret add\fR command\. The data will be encrypted with the public\-keys described by the \fBgit secret tell\fR command\. After using \fBgit secret hide\fR to encrypt your data, it is safe to commit your changes\. \fBNOTE:\fR\. It\'s recommended to add \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\.
+.
+.IP "7." 4
 Later you can decrypt files with the \fBgit secret reveal\fR command, or just show their contents to strdout with the \fBgit secret cat\fR command\. If you used a password on you GPG key (always recommended), it will ask you for your password\. And you\'re done!
 .
 .IP "" 0
@@ -35,13 +38,13 @@ Later you can decrypt files with the \fBgit secret reveal\fR command, or just sh
 Get their \fBgpg\fR public\-key\. \fBYou won\'t need their secret key\.\fR
 .
 .IP "2." 4
-Import this key inside your \fBgpg\fR setup (in ~/\.gnupg or similar) by running \fBgpg \-\-import KEY_NAME\fR
+Import this key into your \fBgpg\fR setup (in ~/\.gnupg or similar) by running \fBgpg \-\-import KEY_NAME\.txt\fR
 .
 .IP "3." 4
-Now add this person to your secrets repo by running \fBgit secret tell persons@email\.id\fR
+Now add this person to your secrets repo by running \fBgit secret tell persons@email\.id\fR (this will be the email address assocated with the public key)
 .
 .IP "4." 4
-Then re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR\. (The \-d options deletes the unencrypted file after re\-encrypting it)\. Now the newly added user be able to decrypt them using \fBgit\-secret\fR and their secret key\.
+The newly added user cannot yet read the encrypted files\. Now, re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR, and then commit and push the newly encrypted files\. (The \-d options deletes the unencrypted file after re\-encrypting it)\. Now the newly added user be able to decrypt the files in the repo by using \fBgit\-secret\fR and their gpg installation (with their secret key)\.
 .
 .IP "" 0
 .
@@ -49,10 +52,10 @@ Then re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR\.
 Note that it is possible to add yourself to the system without decrypting existing files\. It will be possible to decrypt them after reencrypting them with the new keyring\. So, if you don\'t want unexpected keys added, make sure to configure some server\-side security policy with the \fBpre\-receive\fR hook\.
 .
 .SH "Configuration"
-You can configure several things to suit your workflow better\. To do so, just set the required variable to the value you need\. This can be done in your shell environment file or with the each \fBgit\-secret\fR command\.
+You can configure the version of gpg used, or the extension your encrypted files usess to suit your workflow better\. To do so, just set the required variable to the value you need\. This can be done in your shell environment file or with the each \fBgit\-secret\fR command\.
 .
 .P
-These settings are available to be changed:
+The settings are available to be changed are:
 .
 .IP "\(bu" 4
 \fB$SECRETS_GPG_COMMAND\fR \- sets the \fBgpg\fR alternatives, defaults to \fBgpg\fR\. It can be changed to \fBgpg\fR, \fBgpg2\fR, \fBpgp\fR, \fB/usr/local/gpg\fR or any other value\. After doing so rerun the tests to be sure that it won\'t break anything\. Tested to be working with: \fBgpg\fR, \fBgpg2\fR\.
@@ -63,10 +66,10 @@ These settings are available to be changed:
 .IP "" 0
 .
 .SH "Internals \-\- the <code>\.gitsecret</code> folder"
-This folder contains all the information about the data encrypted in this repo\. Use the \'git secret\' commands to manipulate these files, you should not change the data in these files directly\.
+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\.
 .
 .P
-The data is separated into two directories:
+The git\-secret internal data is separated into two directories:
 .
 .SS "<code>\.gitsecret/paths</code>"
 which currently contains only the file \fBmapping\.cfg\fR, which lists all the files your storing encrypted\. In other words, the path mappings: what files are tracked to be hidden and revealed\.
@@ -75,10 +78,10 @@ which currently contains only the file \fBmapping\.cfg\fR, which lists all the f
 All the other internal data is stored in the directory:
 .
 .SS "<code>\.gitsecret/keys</code>"
-This folder contains data used by git\-secret and PGP to allow and maintain the correct encyption and access rights for the allowed parties\.
+This folder contains data used by git\-secret and PGP to allow and maintain the correct encyption and access rights for the permitted parties\.
 .
 .P
-Generally speaking, all the files in this directory except \fBrandom_seed\fR should be checked into your secrets repo\.
+Generally speaking, all the files in this directory [except] \fBrandom_seed\fR should be checked into your secrets repo\.
 .
 .br
 By default, \fBgit secret init\fR will add the file \fB\.gitsecret/keys/random_seed\fR to your \.gitignore file\.

man/man7/git-secret.7.ronn

@@ -3,35 +3,36 @@
 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. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created, **note** that `.gitsecret/` folder with the exception of the random_seed file [should **not** ignored via inclusion in your .gitignore file](https://github.com/sobolevn/git-secret/issues/39).
-2. Add first user to the system by running `git secret tell your@gpg.email`.
-3. 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.
-4. 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.
-5. Later you can decrypt files with the `git secret reveal` command, or just show their contents to strdout with the `git secret cat` command. If you used a password on you GPG key (always recommended), it will ask you for your password. And you're done!
+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** that the contents of the `.gitsecret/` folder should all be checked in, with the exception of the random_seed file. In other words, only the random_seen file should be mentioned in your .gitignore file]
+3. Add 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 strdout with the `git secret cat` command. If you used a password on you GPG key (always recommended), it will ask you for your password. And you're done!
 
 ### I want to add someone to the repository
 
 1. Get their `gpg` public-key. **You won't need their secret key.**
-2. Import this key inside your `gpg` setup (in ~/.gnupg or similar) by running `gpg --import KEY_NAME`
-3. Now add this person to your secrets repo by running `git secret tell persons@email.id`
-4. Then re-encrypt the files using `git secret reveal; git secret hide -d`. (The -d options deletes the unencrypted file after re-encrypting it). Now the newly added user be able to decrypt them using `git-secret` and 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). Now the newly added user be able to decrypt the files in the repo by using `git-secret` and their gpg installation (with their secret key).
 
 Note that it is possible to add yourself to the system without decrypting existing files. It will be possible to decrypt them after reencrypting them with the new keyring. So, if you don't want unexpected keys added, make sure to configure some server-side security policy with the `pre-receive` hook.
 
 ## Configuration
 
-You can configure several things to suit your workflow better. To do so, just set the required variable to the value you need. This can be done in your shell environment file or with the each `git-secret` command.
+You can configure the version of gpg used, or the extension your encrypted files usess  to suit your workflow better. To do so, just set the required variable to the value you need. This can be done in your shell environment file or with the each `git-secret` command.
 
-These settings are available to be changed:
+The settings are available to be changed are:
 
 * `$SECRETS_GPG_COMMAND` - sets the `gpg` alternatives, defaults to `gpg`. It can be changed to `gpg`, `gpg2`, `pgp`, `/usr/local/gpg` or any other value. After doing so rerun the tests to be sure that it won't break anything. Tested to be working with: `gpg`, `gpg2`.
 * `$SECRETS_EXTENSION` - sets the secret files extension, defaults to `.secret`. It can be changed to any valid file extension.
 
 ## Internals -- the `.gitsecret` folder
 
-This folder contains all the information about the data encrypted in this repo. Use the 'git secret' commands to manipulate these files, you should not change the data in these files directly.
+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 `.gitsecret`, you should not change the data in these files directly.
 
-The data is separated into two directories:
+The git-secret internal data is separated into two directories:
 
 ### `.gitsecret/paths`
 
@@ -42,7 +43,7 @@ All the other internal data is stored in the directory:
 
 ### `.gitsecret/keys`
 
-This folder contains data used by git-secret and PGP to allow and maintain the correct encyption and access rights for the allowed parties. 
+This folder contains data used by git-secret and PGP to allow and maintain the correct encyption and access rights for the permitted parties. 
 
-Generally speaking, all the files in this directory except `random_seed` should be checked into your secrets repo.  
+Generally speaking, all the files in this directory [except] `random_seed` should be checked into your secrets repo.  
 By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your .gitignore file.