git-secret/man/man7/git-secret.7.ronn

## Usage

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 [should **not** be ignored](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, otherwise `git-secret` won't allow you to add them, as these files will be stored unencrypted.
4. When done, run `git secret hide` all files, which you have added by `git secret add` command will be encrypted with added public-keys by the `git secret tell` command. Now it is safe to commit your changes. **But**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
5. Now decrypt files with `git secret reveal` command. 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` by running `gpg --import KEY_NAME`
3. Now add this person to the `git-secret` by running `git secret tell persons@email.id`
4. Reencypt the files, now they will be able to decrypt them 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.

These settings are available to be changed:

* `$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

### `.gitsecret` folder

This folder contains every piece of information about the project. It stores:

* public keys for the project
* path mappings. Or in other words: what files are tracked to be hidden and revealed

This folder should not be ignored. In case it is application would not work raising an error: `'.gitsecret/' is ignored. abort.'`. However, it is possible to ignore [individual files](https://github.com/sobolevn/git-secret/issues/93) inside it: `random_seed` would be the most popular example.
new links 2016-02-24 11:27:05 +00:00			`## Usage`
Adds documentation update Documentation: 1. Adds security note, closes #78 2. Adds a tweak about `random_seed` and `.gitsecret/`, closes #93 3. Adds `git --version` into issue tamplate, closes #95 4. Improves `README.md`, refs #79 2017-06-01 11:01:41 +00:00
usage started 2016-02-23 21:11:37 +00:00			These steps cover the basic process of using `git-secret`:
new README 2016-02-24 11:24:07 +00:00
usage started 2016-02-23 21:11:37 +00:00			0. Before starting, make sure you have created `gpg` RSA key-pair: public and secret key identified by your email address.
This is a release commit. Changes: 1. Now everything is tested inside the `docker`-containers and `OSX` images on `travis`. 2. We now have `CONTRIBUTING.md` and `LICENSE.md`. `README.md` is also changed. 3. We have a brand logo. 4. We have autodeploy to `bintray`. 5. Everything is `shellcheck`ed (except `tests/`). Closes #32 #33 #34 #35 #39 2016-07-10 11:28:48 +00:00			1. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created, note that `.gitsecret/` folder [should not be ignored](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, otherwise `git-secret` won't allow you to add them, as these files will be stored unencrypted.
Update git-secret.7.ronn 2016-03-12 15:37:52 +00:00			4. When done, run `git secret hide` all files, which you have added by `git secret add` command will be encrypted with added public-keys by the `git secret tell` command. Now it is safe to commit your changes. But. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
usage started 2016-02-23 21:11:37 +00:00			5. Now decrypt files with `git secret reveal` command. It will ask you for your password. And you're done!

			`### I want to add someone to the repository`
Adds documentation update Documentation: 1. Adds security note, closes #78 2. Adds a tweak about `random_seed` and `.gitsecret/`, closes #93 3. Adds `git --version` into issue tamplate, closes #95 4. Improves `README.md`, refs #79 2017-06-01 11:01:41 +00:00
Replace 'his' with 'their' 2018-02-07 09:42:08 +00:00			1. Get their `gpg` public-key. You won't need their secret key.
usage started 2016-02-23 21:11:37 +00:00			2. Import this key inside your `gpg` by running `gpg --import KEY_NAME`
			3. Now add this person to the `git-secret` by running `git secret tell persons@email.id`
Update git-secret.7.ronn 2016-03-12 15:37:52 +00:00			`4. Reencypt the files, now they will be able to decrypt them with their secret key.`
usage started 2016-02-23 21:11:37 +00:00
new README 2016-02-24 11:24:07 +00:00			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.
usage started 2016-02-23 21:11:37 +00:00
Added `-i` flag to the `git-secret-add` command, which now auto-ignores unignored files. Also added a test case for this feature. Other changes: 1. refactored `Makefile` to have `.PHONY` marks 2. added install target to the `Makefile`, now one can run `make install` (with optional `$PREFIX` variable) 3. updated docs for `git-secret.7`, `git-secret-add.1` 4. refactored some commands to `shift` arguments 5. added a test case to the 'other-file-extension' situation 5. added `.github` folder to store templates Closed #18 2016-05-14 11:03:33 +00:00			`## Configuration`
Adds documentation update Documentation: 1. Adds security note, closes #78 2. Adds a tweak about `random_seed` and `.gitsecret/`, closes #93 3. Adds `git --version` into issue tamplate, closes #95 4. Improves `README.md`, refs #79 2017-06-01 11:01:41 +00:00
Added `-i` flag to the `git-secret-add` command, which now auto-ignores unignored files. Also added a test case for this feature. Other changes: 1. refactored `Makefile` to have `.PHONY` marks 2. added install target to the `Makefile`, now one can run `make install` (with optional `$PREFIX` variable) 3. updated docs for `git-secret.7`, `git-secret-add.1` 4. refactored some commands to `shift` arguments 5. added a test case to the 'other-file-extension' situation 5. added `.github` folder to store templates Closed #18 2016-05-14 11:03:33 +00:00			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.

			`These settings are available to be changed:`

small grammar change 2018-04-14 00:36:33 +00:00			* `$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`.
Added `-i` flag to the `git-secret-add` command, which now auto-ignores unignored files. Also added a test case for this feature. Other changes: 1. refactored `Makefile` to have `.PHONY` marks 2. added install target to the `Makefile`, now one can run `make install` (with optional `$PREFIX` variable) 3. updated docs for `git-secret.7`, `git-secret-add.1` 4. refactored some commands to `shift` arguments 5. added a test case to the 'other-file-extension' situation 5. added `.github` folder to store templates Closed #18 2016-05-14 11:03:33 +00:00			* `$SECRETS_EXTENSION` - sets the secret files extension, defaults to `.secret`. It can be changed to any valid file extension.
Adds documentation update Documentation: 1. Adds security note, closes #78 2. Adds a tweak about `random_seed` and `.gitsecret/`, closes #93 3. Adds `git --version` into issue tamplate, closes #95 4. Improves `README.md`, refs #79 2017-06-01 11:01:41 +00:00
			`## Internals`

			### `.gitsecret` folder

			`This folder contains every piece of information about the project. It stores:`

			`* public keys for the project`
			`* path mappings. Or in other words: what files are tracked to be hidden and revealed`

			This folder should not be ignored. In case it is application would not work raising an error: `'.gitsecret/' is ignored. abort.'`. However, it is possible to ignore [individual files](https://github.com/sobolevn/git-secret/issues/93) inside it: `random_seed` would be the most popular example.