<div dir="ltr">I was reading the pass man page that I have not looked at for along time and found it really confusing. I can figure things out, but new users sure get bad impression. The terminology is mix of pass-name, password, (old-|new-)path, names of passwords -- all without clearly defining terms. The convention that the password is stored in the first line of the password file, but the file can contain additional lines of information should be presented more prominently. A rewrite is clearly needed.<div><br></div><div><div>Especially confusing lines:</div><div><br></div><div>- init [ --path=sub-folder, -p sub-folder ] gpg-id...</div><div>  command line programs like pass deal with directories, not folders </div><div>- find pass-names</div><div>  pass-names is a space separated list of substrings that match pass-names.</div><div>- cp|mv old-path new-path<div><div class="gmail_signature"><div dir="ltr"><div></div></div></div></div></div></div><div>  Documentation for these talk about directories without making it clear that it is talking about pass directories that are inside PASSWORD_STORE_DIR, not file system directories.</div><div>- SIMPLE EXAMPLES/List existing passwords in store</div><div>  Lists directories and pass-names, not passwords</div><div>- SIMPLE EXAMPLES/Find existing passwords in store that match .com</div><div>  Finds pass-names, not passwords<br><div>- SIMPLE EXAMPLES/Add multiline password to store</div><div>  Adds multiple lines, but only one line can be copied to the clipboard at the time, so calling it a multiline password.</div><div><br></div><div>I am sure there are more.</div><div><br></div><div><br></div><div>In my opinion the man page needs a paragraph explaining the terms and conventions to be more inline with the information in pass home page. These then need to be followed consistently. Below is text that includes the most important points and can be used as a starting point for additional text in the man page. (The first item is in already the man page.)</div><div><br></div><div>- *password file* is an gpg2(1) encrypted file inside a directory tree at PASSWORD_STORE_DIR that defaults to ' ~/.password-store'. </div><div>- The name of the password file is the *password name* (alias *pass-name*) with extension '.gpg'. The extension nor the PASSWORD_STORE_DIR is never included in the pass arguments. E.g. 'doorcode'.</div><div>- If the password file is placed in a subdirectory, the name has to include the whole  *path*  to identify the password file. Some commands also work on directories. E.g. 'myhome/doorcode'.<div><div><div>- The *password* is stored in the first line of the password file by convention. The password string consists of (printable|any characters, except which ones?) characters excluding the new line character. Use option '--clip|-c' to copy the password to the clipboard without displaying it.</div><div>- Subsequent lines of the password file can be used to store free and semistructured text that can be copied to the clipboard one line at the time by giving a numerical argument to the '--clip|-c' option.</div><div><br></div><div>Best,</div><div><br></div><div>     -Heikki<br></div><div><div><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><br style="font-size:small"><span style="font-size:small">Heikki Lehväslaiho - skype:heikki_lehvaslaiho </span><span style="font-size:small">cell: +358 40 850 6640</span><br style="font-size:small"><a href="http://about.me/heikki" target="_blank">http://about.me/heikki</a></div></div></div></div></div>
</div></div></div></div></div></div>