commit ddb59757f5e4a6c30ede99a2d4f039e881132ab9
parent 8769aa6370cd6b4ebd7393c32519a04772f5bd29
Author: Jason A. Donenfeld <Jason@zx2c4.com>
Date: Mon, 3 Sep 2012 17:57:46 +0200
Move examples into manpage.
Diffstat:
4 files changed, 224 insertions(+), 93 deletions(-)
diff --git a/README b/README
@@ -8,99 +8,20 @@ This is a very simple password store that encrypts passwords using gpg and
places the encrypted password in a directory. It can generate new passwords
and keep track of old ones.
-If the password storage directory ($HOME/.password-store) is also a git
-repository, add/remove/change operations will create a corresponding git
-commit.
+Please see the man page for considerable more documentation and examples.
-Usage:
- pass init gpg-id
- Initialize new password storage and use gpg-id for encryption.
- pass [ls] [subfolder]
- List passwords.
- pass [show] [--clip,-c] pass-name
- Show existing password and optionally put it on the clipboard.
- If put on the clipboard, it will be cleared in 45 seconds.
- pass insert [--multiline,-m] pass-name
- Insert new optionally multiline password.
- pass generate [--no-symbols,-n] [--clip,-c] pass-name pass-length
- Generate a new password of pass-length with optionally no symbols.
- Optionally put it on the clipboard and clear board after 45 seconds.
- pass rm pass-name
- Remove existing password.
- pass push
- If the password store is a git repository, push the latest changes.
- pass pull
- If the password store is a git repository, pull the latest changes.
- pass git git-command-args...
- If the password store is a git repository, execute a git command
- specified by git-command-args.
- pass help
- Show this text.
+You may read the man page without installing the package by one of these
+commands:
-See the man page for more options -- man 1 pass.
+- Show it in man:
+ $ man ./man/pass.1
-Examples:
+- Produce an HTML page:
- - Initialize password store:
-
- zx2c4@laptop ~ $ pass init Jason@zx2c4.com
- mkdir: created directory ‘/home/zx2c4/.password-store’
- Password store initialized for Jason@zx2c4.com.
-
- - List existing passwords in store:
+ $ groff -mandoc -T html ./man/pass.1 > pass-man-page.html
- zx2c4@laptop ~ $ pass
- ├── Business
- │ ├── some-silly-business-site.com
- │ └── another-business-site.net
- ├── Email
- │ ├── donenfeld.com
- │ └── zx2c4.com
- └── France
- ├── bank
- ├── freebox
- └── mobilephone
-
- Alternatively, "pass ls".
-
- - Show existing password:
-
- zx2c4@laptop ~ $ pass Email/zx2c4.com
- sup3rh4x3rizmynam3
-
- - Add password to store:
-
- zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
- Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
-
- Or, multiline passwords:
-
- zx2c4@laptop ~ $ pass insert --multiline Business/cheese-whiz-factory
- Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
-
- Hey this is my
- awesome
- multi
- line
- passworrrrrrrrd.
- ^D
-
- - Generate new password:
-
- zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
- The generated password to Email/jasondonenfeld.com is:
- $(-QF&Q=IN2nFBx
-
- Or, with no symbols:
-
- zx2c4@laptop ~ $ pass generate --no-symbols Email/jasondonenfeld.com 12
- The generated password to Email/jasondonenfeld.com is:
- YqFsMkBeO6di
-
- - Remove password from store:
-
- zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
- rm: remove regular file ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’? y
- removed ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’
+- Produce a PDF document:
+ $ groff -mandoc ./man/pass.1 pass-man-page.ps
+ $ ps2pdf pass-man-page.ps
diff --git a/man/example-filter.sh b/man/example-filter.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# This is a super bootleg script for converting plaintext examples into groff.
+
+while read line; do
+ echo "$line" | while read -n 1 char; do
+ if [[ $char == "%" ]]; then
+ echo -n '%'
+ continue
+ fi
+ ord=$(printf '%d' "'$char")
+ if [[ $ord -eq 0 ]]; then
+ printf ' '
+ elif [[ $ord -gt 127 ]]; then
+ printf '\[u%X]' "'$char"
+ else
+ printf "$char"
+ fi
+ done
+ echo
+ echo ".br"
+done
diff --git a/man/pass.1 b/man/pass.1
@@ -36,11 +36,17 @@ the valid commands listed below.
Several of the commands below rely on or provide additional functionality if
the password store directory is also a git repository. If the password store
directory is a git repository, all password store modification commands will
-cause a corresponding git commit.
+cause a corresponding git commit. See the \fIEXAMPLES\fP section for an
+extended description using \fBinit\fP and
+.BR git (1).
The \fBinit\fP command must be run before other commands in order to initialize
the password store with the correct gpg key id.
+There is a corresponding bash completion script for use with tab completing
+password names in
+.BR bash (1).
+
.SH COMMANDS
.TP
@@ -100,13 +106,195 @@ using the password store as the git repository.
\fBhelp\fP
Show usage message.
+.SH EXAMPLES
+
+.TP
+Initialize password store
+.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
+.br
+Password store initialized for Jason@zx2c4.com.
+.TP
+List existing passwords in store
+.B zx2c4@laptop ~ $ pass
+.br
+Password Store
+.br
+\[u251C]\[u2500]\[u2500] Business
+.br
+\[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com
+.br
+\[u2502] \[u2514]\[u2500]\[u2500] another-business-site.net
+.br
+\[u251C]\[u2500]\[u2500] Email
+.br
+\[u2502] \[u251C]\[u2500]\[u2500] donenfeld.com
+.br
+\[u2502] \[u2514]\[u2500]\[u2500] zx2c4.com
+.br
+\[u2514]\[u2500]\[u2500] France
+.br
+ \[u251C]\[u2500]\[u2500] bank
+.br
+ \[u251C]\[u2500]\[u2500] freebox
+.br
+ \[u2514]\[u2500]\[u2500] mobilephone
+.br
+
+.br
+Alternatively, "\fBpass ls\fP".
+.TP
+Show existing password
+.B zx2c4@laptop ~ $ pass Email/zx2c4.com
+.br
+sup3rh4x3rizmynam3
+.TP
+Copy existing password to clipboard
+.B zx2c4@laptop ~ $ pass -c Email/zx2c4.com
+.br
+Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds.
+.TP
+Add password to store
+.B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
+.br
+Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
+.TP
+Add multiline password to store
+.B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
+.br
+Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
+.br
+
+.br
+Hey this is my
+.br
+awesome
+.br
+multi
+.br
+line
+.br
+passworrrrrrrrd.
+.br
+^D
+.TP
+Generate new password
+.B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
+.br
+The generated password to Email/jasondonenfeld.com is:
+.br
+$(-QF&Q=IN2nFBx
+.TP
+Generate new alphanumeric password
+.B zx2c4@laptop ~ $ pass -n generate Email/jasondonenfeld.com 12
+.br
+The generated password to Email/jasondonenfeld.com is:
+.br
+YqFsMkBeO6di
+.TP
+Generate new password and copy it to the clipboard
+.B zx2c4@laptop ~ $ pass -c generate Email/jasondonenfeld.com 19
+.br
+Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
+.TP
+Remove password from store
+.B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y
+.br
+removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
+.TP
+Initialize new password store, create a git repository, and then manipulate and sync passwords
+.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
+.br
+Password store initialized for Jason@zx2c4.com.
+.br
+.B zx2c4@laptop ~ $ pass git init
+.br
+Initialized empty Git repository in /home/zx2c4/.password-store/.git/
+.br
+.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
+.br
+.B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019]
+.br
+[master (root-commit) 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store.
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+create mode 100644 Amazon/amazonemail@email.com.gpg
+.br
+The generated password to Amazon/amazonemail@email.com is:
+.br
+<5m,_BrZY`antNDxKN<0A
+.br
+.B zx2c4@laptop ~ $ pass push -u --all
+.br
+Counting objects: 4, done.
+.br
+Delta compression using up to 2 threads.
+.br
+Compressing objects: 100% (3/3), done.
+.br
+Writing objects: 100% (4/4), 921 bytes, done.
+.br
+Total 4 (delta 0), reused 0 (delta 0)
+.br
+To kexec.com:pass-store
+.br
+* [new branch] master -> master
+.br
+Branch master set up to track remote branch master from origin.
+.br
+.B zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com
+.br
+Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88**
+.br
+[master b9b6746] Added given password for Amazon/otheraccount@email.com to store.
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+create mode 100644 Amazon/otheraccount@email.com.gpg
+.br
+.B zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]? y
+.br
+removed \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]
+.br
+rm 'Amazon/amazonemail@email.com.gpg'
+.br
+[master 288b379] Removed Amazon/amazonemail@email.com from store.
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+delete mode 100644 Amazon/amazonemail@email.com.gpg
+.br
+.B zx2c4@laptop ~ $ pass push
+.br
+Counting objects: 9, done.
+.br
+Delta compression using up to 2 threads.
+.br
+Compressing objects: 100% (5/5), done.
+.br
+Writing objects: 100% (7/7), 1.25 KiB, done.
+.br
+Total 7 (delta 0), reused 0 (delta 0)
+.br
+To kexec.com:pass-store
+
.SH FILES
.TP
-\fB~/.password-store\fP
+.B ~/.password-store
The password storage directory.
.TP
-\fB~/.password-store/.gpg-id\fP
+.B ~/.password-store/.gpg-id
Contains the gpg key identification used for encryption and decryption. This should
be set using the \fBinit\fP command.
diff --git a/src/password-store.sh b/src/password-store.sh
@@ -227,7 +227,7 @@ case "$command" in
fi
;;
git)
- if [[ -d $GIT ]]; then
+ if [[ $1 == "init" ]] || [[ -d $GIT ]]; then
exec git $@
else
echo "Error: the password store is not a git repository."
