From a3ee07c2f1ce4ab3631f4289792a5c97af8e5885 Mon Sep 17 00:00:00 2001 From: Josh Rabinowitz Date: Mon, 11 Feb 2019 09:37:09 -0500 Subject: [PATCH] documentation update (#355) --- _posts/2019-02-11-git-secret-add.md | 44 +++++++++ _posts/2019-02-11-git-secret-cat.md | 36 +++++++ _posts/2019-02-11-git-secret-changes.md | 39 ++++++++ _posts/2019-02-11-git-secret-clean.md | 35 +++++++ _posts/2019-02-11-git-secret-hide.md | 65 +++++++++++++ _posts/2019-02-11-git-secret-init.md | 36 +++++++ _posts/2019-02-11-git-secret-killperson.md | 35 +++++++ _posts/2019-02-11-git-secret-list.md | 37 +++++++ _posts/2019-02-11-git-secret-remove.md | 39 ++++++++ _posts/2019-02-11-git-secret-reveal.md | 46 +++++++++ _posts/2019-02-11-git-secret-tell.md | 42 ++++++++ _posts/2019-02-11-git-secret-usage.md | 34 +++++++ _posts/2019-02-11-git-secret-whoknows.md | 35 +++++++ _posts/2019-02-11-git-secret.md | 106 +++++++++++++++++++++ 14 files changed, 629 insertions(+) create mode 100644 _posts/2019-02-11-git-secret-add.md create mode 100644 _posts/2019-02-11-git-secret-cat.md create mode 100644 _posts/2019-02-11-git-secret-changes.md create mode 100644 _posts/2019-02-11-git-secret-clean.md create mode 100644 _posts/2019-02-11-git-secret-hide.md create mode 100644 _posts/2019-02-11-git-secret-init.md create mode 100644 _posts/2019-02-11-git-secret-killperson.md create mode 100644 _posts/2019-02-11-git-secret-list.md create mode 100644 _posts/2019-02-11-git-secret-remove.md create mode 100644 _posts/2019-02-11-git-secret-reveal.md create mode 100644 _posts/2019-02-11-git-secret-tell.md create mode 100644 _posts/2019-02-11-git-secret-usage.md create mode 100644 _posts/2019-02-11-git-secret-whoknows.md create mode 100644 _posts/2019-02-11-git-secret.md diff --git a/_posts/2019-02-11-git-secret-add.md b/_posts/2019-02-11-git-secret-add.md new file mode 100644 index 00000000..32b9dd59 --- /dev/null +++ b/_posts/2019-02-11-git-secret-add.md @@ -0,0 +1,44 @@ +--- +layout: post +title: 'git-secret-add' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-add +categories: command +--- +git-secret-add - starts to track added files. +============================================= + +## SYNOPSIS + + git secret add [-i] ... + + +## DESCRIPTION +`git-secret-add` adds a filepath(s) into `.gitsecret/paths/mapping.cfg`. + +When adding files to encrypt, ensure that they are ignored by `git` by mentioning +them in .gitignore, since they must be secure and not be committed into the remote repository unencrypted. + +If there's no users in the `git-secret`'s keyring, when adding a file, an exception will be raised. + +Use the `git secret add` command to add filenames to this file. +It is not recommended to add filenames directly into `.gitsecret/paths/mapping.cfg`. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + +## OPTIONS + + -i - adds given files to `.gitignore` if they're not there already + -h - shows this help. + + +## MANUAL + +Run `man git-secret-add` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal) diff --git a/_posts/2019-02-11-git-secret-cat.md b/_posts/2019-02-11-git-secret-cat.md new file mode 100644 index 00000000..fe282a42 --- /dev/null +++ b/_posts/2019-02-11-git-secret-cat.md @@ -0,0 +1,36 @@ +--- +layout: post +title: 'git-secret-cat' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-cat +categories: command +--- +git-secret-cat - decrypts files passed on command line to stdout +============================================= + +## SYNOPSIS + + git secret cat [-d dir] [-p password] filename [filenames] + + +## DESCRIPTION +`git-secret-cat` - Outputs to stdout the contents of the files named on the command line. +As with `git-secret-reveal`, you'll need to have a public/private keypair that is allowed to +decrypt this repo. + + +## OPTIONS + + -d - specifies `--homedir` option for the `gpg`, basically use this option if you store your keys in a custom location. + -p - specifies password for noinput mode, adds `--passphrase` option for `gpg`. + -h - shows help. + + +## MANUAL + +Run `man git-secret-cat` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret-changes.md b/_posts/2019-02-11-git-secret-changes.md new file mode 100644 index 00000000..bd5d8f99 --- /dev/null +++ b/_posts/2019-02-11-git-secret-changes.md @@ -0,0 +1,39 @@ +--- +layout: post +title: 'git-secret-changes' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-changes +categories: command +--- +git-secret-changes - view diff of the hidden files. +=================================================== + +## SYNOPSIS + + git secret changes [-h] [-d dir] [-p password] [pathspec]... + + +## DESCRIPTION +`git-secret-changes` - shows changes between the current version of hidden files and the ones already committed. +You can provide any number of hidden files to this command as arguments, and it will show changes for these files only. +Note that files must be specified by their encrypted names, typically `filename.yml.secret`. +If no arguments are provided, information about all hidden files will be shown. + + +## OPTIONS + + -d - specifies `--homedir` option for the `gpg`. Use this option if your store your keys in a custom location. + -p - specifies password for noinput mode, adds `--passphrase` option for `gpg`. + -h - shows help. + + +## MANUAL + +Run `man git-secret-changes` to see this note. + + +## SEE ALSO + +[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), +[git-secret-cat(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret-clean.md b/_posts/2019-02-11-git-secret-clean.md new file mode 100644 index 00000000..494b5604 --- /dev/null +++ b/_posts/2019-02-11-git-secret-clean.md @@ -0,0 +1,35 @@ +--- +layout: post +title: 'git-secret-clean' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-clean +categories: command +--- +git-secret-clean - removes all the hidden files. +================================================ + +## SYNOPSIS + + git secret clean [-v] + + +## DESCRIPTION +`git-secret-clean` deletes all the encrypted files. +Verbose output is enabled with the -v option, in which case the program prints which files are deleted. + + +## OPTIONS + + -v - shows which files are deleted. + -h - shows this help. + + +## MANUAL + +Run `man git-secret-clean` to see this note. + + +## SEE ALSO + +[git-secret-whoknows(1)](http://git-secret.io/git-secret-whoknows), [git-secret-add(1)](http://git-secret.io/git-secret-add), +[git-secret-remove(1)](http://git-secret.io/git-secret-remove), [git-secret-killperson(1)](http://git-secret.io/git-secret-killperson) diff --git a/_posts/2019-02-11-git-secret-hide.md b/_posts/2019-02-11-git-secret-hide.md new file mode 100644 index 00000000..0f78b7cf --- /dev/null +++ b/_posts/2019-02-11-git-secret-hide.md @@ -0,0 +1,65 @@ +--- +layout: post +title: 'git-secret-hide' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-hide +categories: command +--- +git-secret-hide - encrypts all added files with the inner keyring. +================================================================== + +## SYNOPSIS + + git secret hide [-c] [-F] [-P] [-v] [-d] [-m] + + +## DESCRIPTION +`git-secret-hide` creates an encrypted version (typically called `filename.txt.secret`) +of each file added by `git-secret-add` command. +Now anyone enabled via 'git secret tell' can can decrypt these files. Under the hood, +`git-secret` uses the keyring in `.gitsecret/keys` and user's secret keys to decrypt the files. + +It is recommended to encrypt (or re-encrypt) all the files in a git-secret repo each +time `git secret hide` is run. + +Otherwise the keychain (the one stored in `.gitsecret/keys/*.gpg`), +may have changed since the last time the files were encrypted, and it's possible +to create a state where the users in the output of `git secret whoknows` +may not be able to decrypt the some files in the repo, or may be able decrypt files +they're not supposed to be able to. + +In other words, unless you re-encrypt all the files in a repo each time you 'hide' any, +it's possible to make it so some files can no longer be decrypted by users who should be +(and would appear) able to decrypt them, and vice-versa. + +If you know what you are doing and wish to encrypt or re-encrypt only a subset of the files +even after reading the above paragraphs, you can use the -F option to force `git secret hide` +to skip any hidden files where the unencrypted versions aren't present. + +Also, it is possible to modify the names of the encrypted files by setting `SECRETS_EXTENSION` variable. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + + +## OPTIONS + + -v - verbose, shows extra information. + -c - deletes encrypted files before creating new ones. + -F - forces hide to continue if a file to encrypt is missing. + -P - preserve permissions of unencrypted file in encrypted file. + -d - deletes unencrypted files after encryption. + -m - encrypt files only when modified. + -h - shows help. + + +## MANUAL + +Run `man git-secret-hide` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), +[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), +[git-secret-cat(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret-init.md b/_posts/2019-02-11-git-secret-init.md new file mode 100644 index 00000000..2a36ca8b --- /dev/null +++ b/_posts/2019-02-11-git-secret-init.md @@ -0,0 +1,36 @@ +--- +layout: post +title: 'git-secret-init' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-init +categories: command +--- +git-secret-init - initializes git-secret repository. +==================================================== + +## SYNOPSIS + + git secret init + + +## DESCRIPTION +`git-secret-init` should be run inside a `git` repo to set up the .gitsecret directory and initialize the repo for git-secret. +Until repository is initialized with `git secret init`, all other `git-secret` commands are unavailable. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + + +## OPTIONS + + -h - shows this help. + + +## MANUAL + +Run `man git-secret-init` to see this note. + + +## SEE ALSO + +[git-secret-usage(1)](http://git-secret.io/git-secret-usage), [git-secret-tell(1)](http://git-secret.io/git-secret-tell) diff --git a/_posts/2019-02-11-git-secret-killperson.md b/_posts/2019-02-11-git-secret-killperson.md new file mode 100644 index 00000000..4431c848 --- /dev/null +++ b/_posts/2019-02-11-git-secret-killperson.md @@ -0,0 +1,35 @@ +--- +layout: post +title: 'git-secret-killperson' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-killperson +categories: command +--- +git-secret-killperson - deletes key identified by an email from the inner keyring. +================================================================================== + +## SYNOPSIS + + git secret killperson ... + + +## DESCRIPTION +This command removes the keys associated with the selected email addresses from the keyring. +If you remove a keypair's access with `git-secret-killperson`, and run `git-secret-reveal` and `git-secret-hide -r`, +it will be impossible for given users to decrypt the hidden files. + + +## OPTIONS + + -h - shows this help. + + +## MANUAL + +Run `man git-secret-killperson` to see this note. + + +## SEE ALSO + +[git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-remove(1)](http://git-secret.io/git-secret-remove), +[git-secret-clean(1)](http://git-secret.io/git-secret-clean) diff --git a/_posts/2019-02-11-git-secret-list.md b/_posts/2019-02-11-git-secret-list.md new file mode 100644 index 00000000..55fd6e14 --- /dev/null +++ b/_posts/2019-02-11-git-secret-list.md @@ -0,0 +1,37 @@ +--- +layout: post +title: 'git-secret-list' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-list +categories: command +--- +git-secret-list - prints all the added files. +============================================= + +## SYNOPSIS + + git secret list + + +## DESCRIPTION +`git-secret-list` prints all the currently added tracked files from the `.gitsecret/paths/mapping.cfg`. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + + +## OPTIONS + + -h - shows this help. + + +## MANUAL + +Run `man git-secret-list` to see this note. + + +## SEE ALSO + +[git-secret-whoknows(1)](http://git-secret.io/git-secret-whoknows), [git-secret-add(1)](http://git-secret.io/git-secret-add), +[git-secret-remove(1)](http://git-secret.io/git-secret-remove), [git-secret-hide(1)](http://git-secret.io/git-secret-hide), +[git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), [git-secret-cat(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret-remove.md b/_posts/2019-02-11-git-secret-remove.md new file mode 100644 index 00000000..08116fa2 --- /dev/null +++ b/_posts/2019-02-11-git-secret-remove.md @@ -0,0 +1,39 @@ +--- +layout: post +title: 'git-secret-remove' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-remove +categories: command +--- +git-secret-remove - removes files from index. +============================================= + +## SYNOPSIS + + git secret remove [-c] ... + + +## DESCRIPTION +`git-secret-remove` deletes files from `.gitsecret/paths/mapping.cfg`, +so they won't be encrypted or decrypted in the future. +There's also a -c option to delete existing encrypted versions of the files provided. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + + +## OPTIONS + + -c - deletes existing real encrypted files. + -h - shows help. + + +## MANUAL + +Run `man git-secret-remove` to see this note. + + +## SEE ALSO + +[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-clean(1)](http://git-secret.io/git-secret-clean), +[git-secret-killperson(1)](http://git-secret.io/git-secret-killperson) diff --git a/_posts/2019-02-11-git-secret-reveal.md b/_posts/2019-02-11-git-secret-reveal.md new file mode 100644 index 00000000..93cb90b7 --- /dev/null +++ b/_posts/2019-02-11-git-secret-reveal.md @@ -0,0 +1,46 @@ +--- +layout: post +title: 'git-secret-reveal' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-reveal +categories: command +--- +git-secret-reveal - decrypts all added files. +============================================= + +## SYNOPSIS + + git secret reveal [-f] [-F] [-P] [-d dir] [-p password] [pathspec]... + + +## DESCRIPTION +`git-secret-reveal` - decrypts all the files in `.gitsecret/paths/mapping.cfg`, +or the passed `pathspec`s. +You will need to have imported the paired secret-key with one of the +public-keys which were used in the encryption. +Under the hood, this uses the `gpg --decrypt` command. + +(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret +folder using the SECRETS_DIR environment variable. + + +## OPTIONS + + -f - forces gpg to overwrite existing files without prompt. + -F - forces reveal to continue even if a file fails to decrypt. + -d - specifies `--homedir` option for the `gpg`, basically use this option if you store your keys in a custom location. + -p - specifies password for noinput mode, adds `--passphrase` option for `gpg`. + -P - preserve permissions of encrypted file in unencrypted file. + -h - shows help. + + +## MANUAL + +Run `man git-secret-reveal` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-cat(1)](http://git-secret.io/git-secret-cat), +[git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-add(1)](http://git-secret.io/git-secret-add), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide) diff --git a/_posts/2019-02-11-git-secret-tell.md b/_posts/2019-02-11-git-secret-tell.md new file mode 100644 index 00000000..ab9a1157 --- /dev/null +++ b/_posts/2019-02-11-git-secret-tell.md @@ -0,0 +1,42 @@ +--- +layout: post +title: 'git-secret-tell' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-tell +categories: command +--- +git-secret-tell - adds a person, who can access private data. +=============================================================== + +## SYNOPSIS + + git secret tell [-m] [-d dir] [emails]... + + +## DESCRIPTION +`git-secret-tell` receives an email addresses as an input, searches for the `gpg`-key in the `gpg`'s +`homedir` by these emails, then imports a person's public key into the `git-secret`'s inner keychain. +From this moment this person can encrypt new files with the keyring which contains their key, +but they cannot decrypt the old files, which were already encrypted without their key. +The files should be re-encrypted with the new keyring by someone who has the unencrypted files. + +**Do not manually import secret key into `git-secret`**. Anyways, it won't work with any of the secret-keys imported. + + +## OPTIONS + + -m - takes your current `git config user.email` as an identifier for the key. + -d - specifies `--homedir` option for the `gpg`, basically use this option if your store your keys in a custom location. + -h - shows help. + + +## MANUAL + +Run `man git-secret-tell` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-add(1)](http://git-secret.io/git-secret-add), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), +[git-secret-cat(1)](http://git-secret.io/git-secret-cat), [git-secret-killperson(1)](http://git-secret.io/git-secret-killperson) diff --git a/_posts/2019-02-11-git-secret-usage.md b/_posts/2019-02-11-git-secret-usage.md new file mode 100644 index 00000000..0439bd41 --- /dev/null +++ b/_posts/2019-02-11-git-secret-usage.md @@ -0,0 +1,34 @@ +--- +layout: post +title: 'git-secret-usage' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-usage +categories: command +--- +git-secret-usage - prints all the available commands. +===================================================== + +## SYNOPSIS + + git secret usage + + +## DESCRIPTION +`git-secret-usage` is used to print all the available commands. + + +## OPTIONS + + -h - shows this help. + + +## MANUAL + +Run `man git-secret-usage` to see this note. + + +## SEE ALSO + +[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-add(1)](http://git-secret.io/git-secret-add), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), +[git-secret-cat(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret-whoknows.md b/_posts/2019-02-11-git-secret-whoknows.md new file mode 100644 index 00000000..017b3806 --- /dev/null +++ b/_posts/2019-02-11-git-secret-whoknows.md @@ -0,0 +1,35 @@ +--- +layout: post +title: 'git-secret-whoknows' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret-whoknows +categories: command +--- +git-secret-whoknows - prints email-labels for each key in the keyring. +====================================================================== + +## SYNOPSIS + + git secret whoknows + + +## DESCRIPTION +`git-secret-whoknows` prints list of email addresses whose keys are allowed to access the secrets in this repo. + + +## OPTIONS + + -l - 'long' output, shows key expiration dates. + -h - shows this help. + + +## MANUAL + +Run `man git-secret-whoknows` to see this note. + + +## SEE ALSO + +[git-secret-list(1)](http://git-secret.io/git-secret-list), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), +[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), +[git-secret-cat(1)](http://git-secret.io/git-secret-cat) diff --git a/_posts/2019-02-11-git-secret.md b/_posts/2019-02-11-git-secret.md new file mode 100644 index 00000000..4894d03d --- /dev/null +++ b/_posts/2019-02-11-git-secret.md @@ -0,0 +1,106 @@ +--- +layout: post +title: 'git-secret' +date: 2019-02-11 09:26:41 -0500 +permalink: git-secret +categories: 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 ` 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! + +### 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 associated 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 using `git-secret`. + +Note that it is possible to add yourself to the git-secret repo without decrypting existing files. +It will be possible to decrypt them after re-encrypting them with the new keyring. So, if you don't +want unexpected keys added, you can configure some server-side security policy with the `pre-receive` hook. + +## Configuration + +You can configure the version of gpg used, or the extension your encrypted files use, 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 each `git-secret` command. + +The settings 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. + +* `$SECRETS_DIR` - sets the directory where git-secret stores its files, defaults to .gitsecret. +It can be changed to any valid directory name. + +## The `.gitsecret` folder (can be overridden with SECRETS_DIR) + +This folder contains information about the files encrypted by git-secret, +and about which public/private key sets can access the encrypted data. + +You can change the name of this directory using the SECRETS_DIR environment variable. + +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` + +This directory currently contains only the file `mapping.cfg`, which lists all the files your storing encrypted. +In other words, the path mappings: what files are tracked to be hidden and revealed. + +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. + +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. + +Again, you can change the name of this directory using the SECRETS_DIR environment variable.