From 9d8313aaddae79d71c322f9e15e7ed2a8a3d035e Mon Sep 17 00:00:00 2001
From: Yolan Romailler <AnomalRoil@users.noreply.github.com>
Date: Mon, 17 Aug 2020 17:04:20 +0200
Subject: [PATCH] Adding documentation for list (#1526)

RELEASE_NOTES=[DOCUMENTATION] Document list flags

Signed-off-by: Yolan Romailler <yolan@romailler.ch>
---
 docs/commands/list.md | 113 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 docs/commands/list.md

diff --git a/docs/commands/list.md b/docs/commands/list.md
new file mode 100644
index 00000000..2e5978e2
--- /dev/null
+++ b/docs/commands/list.md
@@ -0,0 +1,113 @@
+# `list` command
+
+The `list` command is used to list all the entries in the password store or at a given prefix.
+
+## Synopsis
+
+```bash
+$ gopass ls
+$ gopass ls path/to/entries
+```
+
+- List all the entries in the password store including the one in mounted stores: `gopass list`
+- List all the entries in a given folder showing their relative path from the root: `gopass list path/to/entries`
+
+Note: `list` will not change anything, nor encrypt or decrypt anything.
+
+## Flags
+
+Flag | Aliases | Description
+---- | ------- | -----------
+`--limit value` | `-l value`| Max tree depth (default: -1)
+` --flat `      |` -f`      | Print a flat list of secrets (default: false)
+` --folders`    | `-d`    |  Print a flat list of folders (default: false)
+` --strip-prefix` | `-s`    |  Strip prefix from filtered entries (default: false)
+
+The `--flat` and `--folders` flags provide a plaintext list of the entries located at 
+the given prefix (default prefix being the root `/`). They are notably used to produce the 
+completion results. 
+The `--flat` one will list all entries, one per line, using its full path.
+The `--folders` one will display all the folders, one per line, recursively per level. 
+For instance an entry `folder/sub/entry` would cause it to list both:
+```bash
+$ gopass list --folders
+folder
+folder/sub
+```
+whereas `gopass list --flat` would have just displayed one line: `folder/sub/entry`.
+
+The `--strip-prefix` flag is meant to be used along with `--flat` or `--folders`.
+It will list the relative path from the current prefix, removing the said prefix, 
+instead of listing the relative paths from the root.
+For instance on entry `folder/sub/entry`, running `gopass ls -f -s folder` would display
+ only `sub/entry` instead of `folder/sub/entry`.
+
+The `--limit` flag starts counting its depth from the root store, which means that 
+a depth of 0 only lists the items in the root gopass store:
+```bash
+$ gopass list -l 0
+gopass
+├── bar
+├── foo
+└── test (/home/user/.local/share/gopass/stores/substore1)
+```
+A value of 1 would list all the items in the root, plus their sub-items but no more:
+```bash
+$ gopass list -l 1
+gopass
+├── bar
+│   └── bar
+├── foo
+│   ├── bar
+│   └── foo
+└── test (/home/user/.local/share/gopass/stores/substore1)
+    └── foo
+```
+A negative value lists all the items without any depth limit. 
+```bash
+$ gopass list -l -1
+gopass
+├── bar
+│   └── bar
+├── foo
+│   ├── bar
+│   │   ├── bar
+│   │   │   └── bar
+│   │   └── baz
+│   └── foo
+└── test (/home/user/.local/share/gopass/stores/substore1)
+    └── foo
+```
+
+The flags can be used together: `gopass -l 1 -d` will list only the folders up to a depth of 1:
+```bash
+$ gopass list -l 1 -d
+bar
+foo
+foo/bar
+test
+test/foo
+```
+
+## Shadowing
+It is possible to have a path that is both an entry and a folder. In that case the list command
+will always display the folder and the entry is "shadowed", but it can still be accessed using 
+`gopass show path/to/it`, while the content of the folder can be listed using `gopass list path/to/it`.
+
+It should also be noted that the `mount` command can completely "shadow" an entry in a password store,
+simply by having the same name and this entry and its subentries will not be visible 
+using `ls` anymore until the substore is unmounted.
+The entries shadowed by a mount will not show up in a search and cannot be accessed at all without unmounting.
+
+For instance in our example above, maybe there is an entry test/zaz in the root store, 
+but since the substore is mounted as `test/`, it only displays the content of the substore. 
+Unmounting it reveals its shadowed entries:
+```bash
+$ gopass list test
+test 
+└── foo
+$ gopass mounts rm test
+$ gopass list test
+test 
+└── zaz
+```
\ No newline at end of file