Skip to content

Commit

Permalink
better docs (#383)
Browse files Browse the repository at this point in the history 
* spent some hours giving some care to the docs

* some further touchups
  • Loading branch information
@Zamiell @dominikschulz
Zamiell authored and dominikschulz committed Oct 6, 2017
1 parent fc988ea commit 311c0d8
Show file tree
Hide file tree
Showing 7 changed files with 245 additions and 195 deletions.
92 changes: 47 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<p align="center">
<img src="logo.png" height="500" alt="gopass Gopher by Vincent Leinweber, remixed from the Renée French original Gopher" title="gopass Gopher by Vincent Leinweber, remixed from the Renée French original Gopher" />
<img src="logo.png" height="250" alt="gopass Gopher by Vincent Leinweber, remixed from the Renée French original Gopher" title="gopass Gopher by Vincent Leinweber, remixed from the Renée French original Gopher" />
</p>

# gopass
Expand All @@ -10,65 +10,66 @@

The slightly more awesome Standard Unix Password Manager for Teams. Written in Go.

## Table of Contents

1. [Abstract](#abstract)
2. [Demo](#demo)
3. [Features](#features)
4. [Installation](#installation)
5. [Development](#development)
6. [Credit & License](#credit-&-license)
7. [Community](#community)
8. [Contributing](#contributing)
9. [Acknowledgements](#acknowledgements)
10. [Further Documentation](#further-documentation)

## Abstract

> Password management should be simple and follow [Unix philosophy](http://en.wikipedia.org/wiki/Unix_philosophy). With `pass`, each secret lives inside of a `gpg` encrypted file whose filename is the title of the website or resource that requires the secret. These encrypted files may be organized into meaningful folder hierarchies, copied from computer to computer, and, in general, manipulated using standard command line file management utilities. - [passwordstore.org](https://www.passwordstore.org/)
Our target audience are professional developers and sysadmins (and especially teams of those) who are well versed with a
command line interface. One explicit goal for this project is to make it more approachable to semi- and non-technical users
in the long term as well. We go by the UNIX philosophy and try to do one thing and do it well - always providing stellar
user experience and sane, simple interfaces.
`gopass` is a rewrite of `pass` in [Go](https://golang.org/) with the aim of making it cross-platform and [adding additional features](#features). Our target audience are professional developers and sysadmins (and especially teams of those) who are well versed with a command line interface. One explicit goal for this project is to make it more approachable to non-technical users. We go by the UNIX philosophy and try to do one thing and do it well, providing a stellar user experience and a sane, simple interface.

Warning: _gopass_ currently works on Linux & macOS. Please feel free to help with others.
Warning: `gopass` currently works on Ubuntu & macOS. Please feel free to help with others.

## Demo

[![asciicast](https://asciinema.org/a/101688.png)](https://asciinema.org/a/101688)

## Features

Please see `docs/features.md` for an extensive list of all features along with
several usage examples.

| **Feature** | *State* | Description |
| ----------- | ------- | ----------- |
| **Secure secret storage** | *stable* | Securely storing secrets encrypted with GPG
| **Recipient management** | *beta* | Easily manage multiple users of each store
| **Multiple stores** | *beta* | Mount multiple stores in your root store, like filesystems
| **password quality assistance** | *beta* | Checks existing or new passwords for common flaws
| **Binary support** | *alpha* | Special handling of binary files (automatic Base64 encoding)
| **YAML support** | *alpha* | Special handling for YAML content in secrets
| **password leak checker** | *alpha* | Perform **offline** checks against known leaked passwords
| **PAGER support** | *stable* | Automatically invoke a pager on long output
| **JSON API** | *alpha* | Allow gopass to be used as a native extension for browser plugins
Please see [docs/features.md](https://github.com/justwatchcom/gopass/blob/master/docs/features.md) for an extensive list of all features along with several usage examples.

| **Feature** | *pass* | *gopass* | **State** | **Description** |
| ------------------------------- | ------ | -------- | --------- | ------------------------------------------------------------------- |
| **Secure secret storage** | ✔ | ✔ | *stable* | Securely storing secrets encrypted with GPG |
| **Recipient management** | ❌ | ✔ | *beta* | Easily manage multiple users of each store |
| **Multiple stores** | ❌ | ✔ | *beta* | Mount multiple stores in your root store, like file systems |
| **password quality assistance** | ❌ | ✔ | *beta* | Checks existing or new passwords for common flaws |
| **Binary support** | ❌ | ✔ | *alpha* | Special handling of binary files (automatic Base64 encoding) |
| **YAML support** | ❌ | ✔ | *alpha* | Special handling for YAML content in secrets |
| **password leak checker** | ❌ | ✔ | *alpha* | Perform **offline** checks against known leaked passwords |
| **PAGER support** | ❌ | ✔ | *stable* | Automatically invoke a pager on long output |
| **JSON API** | ❌ | ✔ | *alpha* | Allow `gopass` to be used as a native extension for browser plugins |

## Installation

If you have a Go development environment installed please build from source:
If you have [Go](https://golang.org/) installed:

```bash
go get github.com/justwatchcom/gopass
```

Otherwise please see `docs/setup.md` or the [gopass website](https://www.justwatch.com/gopass/#install) for further instructions.
Otherwise, please see [docs/setup.md](https://github.com/justwatchcom/gopass/blob/master/docs/setup.md).

## Development

This project uses github-flow, i.e. create feature branches from master, open an PR against master
and rebase onto master if necessary.
This project uses [GitHub Flow](https://guides.github.com/introduction/flow/). In other words, create feature branches from master, open an PR against master, and rebase onto master if necessary.

We aim for compatibility with the [latest stable Go Release](https://golang.org/dl/) only.

## Security

Please see `docs/security.md`.

## Configuration

Please see `docs/config.md`.

## Credit & License

`gopass` is maintained by the nice folks from [JustWatch](https://www.justwatch.com/gopass)
and licensed under the terms of the MIT license.
`gopass` is maintained by the nice folks from [JustWatch](https://www.justwatch.com/gopass) and licensed under the terms of the MIT license.

Maintainers of this repository:

Expand All @@ -81,21 +82,22 @@ Please refer to the Git commit log for a complete list of contributors.

`gopass` is developed in the open. Here are some of the channels we use to communicate and contribute:

**IRC**: `#gopass` on [irc.freenode.net](https://freenode.net) ([join via Riot](https://riot.im/app/#/room/#freenode_#gopass:matrix.org))

**Usage mailing list:** [gopass-users](https://groups.google.com/forum/#!forum/gopass-users) - for discussions around gopass usage and community support

**Issue tracker:** Use the [GitHub issue tracker](https://github.com/justwatchcom/gopass/issues) to file bugs and feature requests. If you need support, please send your questions to [gopass-user](https://groups.google.com/forum/#!forum/gopass-users) or ask on IRC rather than filing a GitHub issue.
* IRC: #gopass on [irc.freenode.net](https://freenode.net) ([join via Riot](https://riot.im/app/#/room/#freenode_#gopass:matrix.org))
* Usage mailing list: [gopass-users](https://groups.google.com/forum/#!forum/gopass-users), for discussions around `gopass` usage and community support
* Issue tracker: Use the [GitHub issue tracker](https://github.com/justwatchcom/gopass/issues) to file bugs and feature requests. If you need support, please send your questions to [gopass-user](https://groups.google.com/forum/#!forum/gopass-users) or ask on IRC rather than filing a GitHub issue.

## Contributing

We welcome any contributions. Please see the `CONTRIBUTING.md` file for
instructions on how to submit changes. If your are planning on making
more elaborate or controversial changes, please discuss them on the
mailing list or on IRC before sending a pull request.

**Development mailing list:** [gopass-developers](https://groups.google.com/forum/#!forum/gopass-developers) - for discussions around gopass development
We welcome any contributions. Please see the [CONTRIBUTING.md](https://github.com/justwatchcom/gopass/blob/master/CONTRIBUTING.md) file for instructions on how to submit changes. If your are planning on making more elaborate or controversial changes, please discuss them on the [gopass-developers mailing list](https://groups.google.com/forum/#!forum/gopass-developers) or on IRC before sending a pull request.

## Acknowledgements

`gopass` was initially started by Matthias Loibl and Dominik Schulz. The majority of its development has been sponsored by [JustWatch](https://www.justwatch.com/).

## Further Documentation

* [Security](https://github.com/justwatchcom/gopass/blob/master/docs/security.md)
* [Configuration](https://github.com/justwatchcom/gopass/blob/master/docs/config.md)
* [Caveats](https://github.com/justwatchcom/gopass/blob/master/docs/caveats.md)
* [FAQ](https://github.com/justwatchcom/gopass/blob/master/docs/faq.md)
* [JSON API](https://github.com/justwatchcom/gopass/blob/master/docs/jsonapi.md)
29 changes: 14 additions & 15 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@

Some configuration options are only available through setting environment variables.

| **Option** | *Type* | Description |
| ------------- | --------- | ----------- |
| `CHECKPOINT_DISABLE` | `bool` | Set to any non-empty value to disable calling the GitHub API when running `gopass version`. |
| `GOPASS_DEBUG` | `bool` | Set to any non-empty value to enable verbose debug output |
| **Option** | *Type* | Description |
| -------------------- | -------| ----------- |
| `CHECKPOINT_DISABLE` | `bool` | Set to any non-empty value to disable calling the GitHub API when running `gopass version`. |
| `GOPASS_DEBUG` | `bool` | Set to any non-empty value to enable verbose debug output |

## Configuration Options

`gopass` create a new configration file if not already present during startup.
`gopass` create a new configuration file if not already present during startup.
If a config exists it will attempt to parse and load the settings. If this
fails program execution aborts. If `gopass` can not start because of broken
or incompatible config file move it away (make a backup) and start fresh.
Expand All @@ -26,13 +26,12 @@ the subcommand `gopass config`.

This is a list of options available for `gopass`:

| **Option** | *Type* | Description |
| ------------- | --------- | ----------- |
| `askformore` | `bool` | If enabled - it will ask to add more data after use of `generate` command. |
| `autoimport` | `bool` | Import missing keys stored in the pass repo without asking. |
| `autosync` | `bool` | Always do a `git push` after a commit to the store. Makes sure your local changes are always available on your git remote. |
| `cliptimeout` | `int` | How many seconds the secret is stored when using `-c`. |
| `noconfirm` | `bool` | Do not confirm recipient list when encrypting. |
| `path` | `string` | Path to the root store. |
| `safecontent` | `bool` | Only output _safe content_ (i.e. everything but the first line of a secret) to the terminal. Use _copy_ (`-c`) to retrieve the password in the clipboard. |

| **Option** | *Type* | Description |
| ------------- | -------- | ----------- |
| `askformore` | `bool` | If enabled - it will ask to add more data after use of `generate` command. |
| `autoimport` | `bool` | Import missing keys stored in the pass repo without asking. |
| `autosync` | `bool` | Always do a `git push` after a commit to the store. Makes sure your local changes are always available on your git remote. |
| `cliptimeout` | `int` | How many seconds the secret is stored when using `-c`. |
| `noconfirm` | `bool` | Do not confirm recipient list when encrypting. |
| `path` | `string` | Path to the root store. |
| `safecontent` | `bool` | Only output _safe content_ (i.e. everything but the first line of a secret) to the terminal. Use _copy_ (`-c`) to retrieve the password in the clipboard. |
1 change: 0 additions & 1 deletion docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,3 @@ If you use `gopass` as a library be sure to vendor it and expect breaking change
* [GPGTools](https://gpgtools.org/) for macOS
* [GitHub Help on GPG](https://help.github.com/articles/signing-commits-with-gpg/)
* [Git - the simple guide](http://rogerdudler.github.io/git-guide/)

Loading

0 comments on commit 311c0d8

Please sign in to comment.