More doc improvements (#847)

docs/installation.md

@@ -27,14 +27,13 @@ Also we welcome improvements to tests or `git-secret` code for any platform.
 ## Installation process
 
 There are several ways to install `git-secret`, depending on your OS and distribution.
-They generally all have different installation processes, and we only go into 
-a short explanation, because describing how to install the prerequisites on all
-systems is currently outside the scope of this document. 
+They generally all have different installation processes, so we only go into 
+a short explanation of each. 
 (We welcome documentation improvements.)
 
 ---
 
-### Mac OS X/Homebrew
+### Mac OS X / Homebrew
 
 This is a packaging system for OSX. To install `git-secret` on OSX, you can install
 `homebrew` and then use:
@@ -45,7 +44,7 @@ brew install git-secret
 
 ---
 
-### Debian-Type Systems/`deb` package
+### Debian-Type Systems / `deb` package
 
 `deb` is a packaging system for [Debian](https://www.debian.org/) and related linux
 distributions.
@@ -59,7 +58,7 @@ Pre-requirements: make sure you have installed `apt-transport-https` and `ca-cer
 
 ---
 
-### Red Hat Systems/`rpm` package
+### Red Hat Systems / `rpm` package
 
 `rpm` is a packaging system for Fedora, CentOS, and other Red Hat based linux distributions.
 You can find the `rpm` repository [here](https://gitsecret.jfrog.io/artifactory/git-secret-rpm/).
@@ -70,7 +69,7 @@ You can find the `rpm` repository [here](https://gitsecret.jfrog.io/artifactory/
 
 ---
 
-### Alpine Systems/`apk` package
+### Alpine Systems / `apk` package
 
 `apk` is a packaging system for Alpine.
 You can find the `apk` `git-secret` packaging 
@@ -84,7 +83,7 @@ and you can see a list of supported architectures
 
 ---
 
-### Arch Linux/`PKGBUILD` or `AUR`
+### Arch Linux / `PKGBUILD` or `AUR`
 
 The _Arch_ way to install git-secret is to use the directions for
 "Installing Packages" at [Arch User Repository Documentation](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages)
@@ -99,22 +98,23 @@ yay -S git-secret
 
 ---
 
-### Windows/`WSL`, `Cygwin`, `MSYS`, or `Mingw-w64`
+### Windows / `WSL`, `Cygwin`, `MSYS`, or `Mingw-w64`
 
 `git-secret` depends on many unix tools and features that Windows systems do not usually
 include by default.  Therefore to get `git-secret` running on Windows you have to 
 install these tools, probably using one of the toolkits described below. 
-(Each has a different install and setup process, and there may be additional 
-package systems to install the prerequisites on Windows).
+Each has a different install and setup process. There may also be other 
+ways to install the unix prerequisites on Windows.
 
-Then, once the prerequisite unix tools are installed,
+Once the prerequisite unix tools are installed,
 you can use the Manual Installation instructions below to 
 manually install `git-secret` (see below).  
 
-Some options to install the required unix tools on your windows system include
-WSL, CYGWIN, MSYS, and Mingw-w64 (which may have some overlap).
+Some ways to install the required unix tools on windows include
+WSL, CYGWIN, MSYS, and Mingw-w64 
+(internally, these tools may share some components).
 
-Documenting how each is installed and operates is beyond the scope of this document, 
+Documenting how each is installed and used is beyond the scope of this document, 
 so we will cover the topic in broad strokes. Improvements to this documentation
 (or any other git-secret documentation) are welcome. 
 
@@ -125,31 +125,28 @@ Again, after you install the unix tools needed, you can install
 
 Perhaps the easiest way to get `git-secret` operating on windows is using `WSL`
 (if your system supports it). 
-You'll need to install these additional packages: `gnupg make man git gawk file`.
 Here are instructions to install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)
+You'll need to install these additional packages: `gnupg`, `make`, `man`, `git`, `gawk`, `file`.
 
 We have successfully set up automated testing of `git-secret` on `WSL`, 
 so we are confident this method works.
 
 #### Mingw-w64
 
-One way to install the prerequisites for `git-secret` on Windows is to use 
+Another way to install the prerequisites for `git-secret` on Windows is to use 
 [Mingw-w64](https://www.mingw-w64.org/) and install the needed packages.
 By default, the `Mingw-w64` installation will be saved to `C:\msys64`. You'll need to 
 install `make` and probably other tools such as `gnupg`, `make`, `man`, `git`, and `gawk`. 
-(This list might not be complete). Again we have automated testing of `git-secret` on `WSL`
-so we are confident this method works.
+(This list might not be complete). 
 
 #### MSYS and Cygwin
 
-It should also be possible to use `git-secret` with [MSYS](https://www.msys2.org/)
-or [Cygwin](https://www.cygwin.com/), and we have gotten _most_ of the way to getting
+`git-secret` also works with [MSYS](https://www.msys2.org/)
+and [Cygwin](https://www.cygwin.com/), and we have gotten _most_ of the way to getting
 `git-secret`'s self-tests running on these setups with Windows (see 
 [windows-related issues](https://github.com/sobolevn/git-secret/issues?q=is%3Aissue+is%3Aopen+windows).
 
-If you can help with getting the tests to work on additional platforms, and/or updating
-these docs please do!  We welcome contributions `git-secret`, and to this documentation 
-(as well as to other git-secret docs or code).
+We welcome contributions to `git-secret` and its documentation .
 
 ---
 
@@ -161,7 +158,7 @@ cd git-secret && make build
 PREFIX="/usr/local" make install
 ```
 
-Note that you can change prefix to be any directory you subsequently include in in your `PATH`
+Note that you can change `PREFIX` to be any directory you subsequently include in in your `PATH`
 environment variable. We generally recommend you stick to the the default 
 install locations for simplicity, but if you know what you're doing you are welcome to change it.
 

man/man7/git-secret.7.md

@@ -42,13 +42,18 @@ And you're done!
 ### Usage: Adding someone to a repository using git-secret
 
 1. [Get their `gpg` public-key](#using-gpg). **You won't need their secret key.**
+They can export their public key for you using a command like:
 
-2. Import this key into your `gpg` keyring (in `~/.gnupg` or similar) by running `gpg --import KEY_NAME.txt`
+```shell
+gpg --armor --export their@email.com > public_key.txt   # armor here makes it ascii
+```
+ 
+2. Import this key into your `gpg` keyring (in `~/.gnupg` or similar) by running `gpg --import public_key.txt`
 
-3. Now add this person to your secrets repo by running `git secret tell persons@email.id`
+3. Now add this person to your secrets repo by running `git secret tell their@email.id`
 (this will be the email address associated with their public key)
 
-4. Now remove the other user's public key from your personal keyring with `gpg --delete-keys persons@email.id`
+4. Now remove the other user's public key from your personal keyring with `gpg --delete-keys their@email.id`
 
 5. 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.
@@ -92,9 +97,9 @@ with the changes in your code.
 
 One way of doing it is the following:
 
-1. [create a gpg key](#using-gpg) for your CI/CD environment. You can chose any name and email address you want: for instance `MyApp CodeShip <myapp@codeship.com>`
-if your app is called MyApp and your CI/CD provider is CodeShip. It is easier not to define a passphrase for that key. However, if defining a passphrase is unavoidable, use a unique passphrase for the private key.
-2. run `gpg --armor --export-secret-key myapp@codeship.com` to get your private key value
+1. [create a gpg key](#using-gpg) for your CI/CD environment. You can chose any name and email address you want: for instance `MyApp Example <myapp@example.com>`
+if your app is called MyApp and your CI/CD provider is Example. It is easier not to define a passphrase for that key. However, if defining a passphrase is unavoidable, use a unique passphrase for the private key.
+2. run `gpg --armor --export-secret-key myapp@example.com` to get your private key value
 3. Create an env var on your CI/CD server `GPG_PRIVATE_KEY` and assign it the private key value. If a passphrase has been setup for the private key, create another env var on the CI/CD server `GPG_PASSPHRASE` and assign it the passphrase of the private key.
 4. Then write your Continuous Deployment build script. For instance:
 
@@ -160,8 +165,8 @@ 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, and some versions of gpg
-might not work well with keyrings created with newer versions of gpg. 
+vary slightly across different versions of gpg. Also, some versions of gpg
+might not work well with keyrings created or modified with newer 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 by installing matching versions of gpg 
 and using `SECRETS_GPG_COMMAND` environment variable.
@@ -169,7 +174,13 @@ and using `SECRETS_GPG_COMMAND` environment variable.
 For example, 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').
-This is not the only issue it is possible to encounter.
+
+This is not the only issue it is possible to encounter sharing files between different versions
+of `gpg`.
+Generally you are most likely to encounter issues between `gpg`
+versions if you use `git-secret tell` or `git-secret removeperson` to modify
+your repo's `git-secret` keyring using a newer version of `gpg`, and then try to operate
+on that keyring using an older version of `gpg`.
 
 The `git-secret` internal data is separated into two directories:
 
@@ -182,13 +193,16 @@ All the other internal data is stored in the directory:
 
 ### `.gitsecret/keys`
 
-This directory contains data used by git-secret and PGP to allow and maintain the correct encryption and access rights for the permitted parties.
+This directory contains data used by `git-secret` and `gpg` to encrypt files to 
+be accessed by the permitted users.
+
+In particular, this directory contains a `gnupg keyring` with public keys for the emails used with `tell`.
 
-In particular, this directory contains a keyring with all the public keys for the emails used with `tell`.
 This is the keyring used to encrypt files with `git-secret-hide`. 
-`git-secret-reveal` and `git-secret-cat` 
-instead use the user's private keys (which probably reside somewhere like ~/.gnupg/)
-and which are not in the `.gitsecret/keys` directory.
+
+`git-secret-reveal` and `git-secret-cat`, which decrypt secrets,
+instead use the user's _private keys_ (which probably reside somewhere like ~/.gnupg/).
+Note that user's private keys, needed for decryption, are _not_ in the `.gitsecret/keys` directory.
 
 Generally speaking, all the files in this directory *except* `random_seed` should be checked into your repo.
 By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your `.gitignore` file.