staging area documentation

13 files changed, 83 insertions, 19 deletions

diff --git a/website/docs/community.md b/website/docs/community.md
index ed9d8f9..51c20f9 100644
--- a/website/docs/community.md
+++ b/website/docs/community.md
@@ -13,6 +13,8 @@ If you're French speaking, you might prefer to directly come where other French
 
 [![Chat on Miaou](https://miaou.dystroy.org/static/shields/room-fr.svg?v=1)](https://miaou.dystroy.org/3) **Code & Croissants**
 
+Don't hesitate to come if you have a question.
+
 # Issues
 
 We use [GitHub's issue manager](https://github.com/Canop/broot/issues).
diff --git a/website/docs/conf_verbs.md b/website/docs/conf_verbs.md
index 4af35be..85e1b99 100644
--- a/website/docs/conf_verbs.md
+++ b/website/docs/conf_verbs.md
@@ -352,6 +352,13 @@ invocation | default key | default shortcut | behavior / details
 :toggle_sizes | - | - | toggle the size mode
 :toggle_trim_root | - | - | toggle trimming of top level files in tree display
 :up_tree | - | - | focus the parent of the current root
+:stage | <kbd>+</kbd> | - | add selection to staging area
+:unstage | <kbd>-</kbd> | - | remove selection from staging area
+:toggle_stage | <kbd>ctrl</kbd><kbd>g</kbd> | - | add or remove selection to staging area
+:clear_stage | - | cls | empty the staging area
+:open_staging_area | - | osa | open the staging area
+:close_staging_area | - | csa | close the staging area panel
+:toggle_staging_area | - | tsa | open/close the staging area panel
 
 Note that
 
@@ -360,7 +367,7 @@ Note that
 
 # Input related verbs
 
-Some internal actions can be bound to a key shortcut but can't be called explicitly because they directly act on the input field:
+Some internal actions can be bound to a key shortcut but can't be called explicitly from the input because they directly act on the input field:
 
 name | default binding | behavior
 -|-|-
diff --git a/website/docs/img/20210424-mycnf.png b/website/docs/img/20210424-mycnf.png
index b981f66..ba022ba 100644
--- a/website/docs/img/20210424-mycnf.png
+++ b/website/docs/img/20210424-mycnf.png
diff --git a/website/docs/img/20210424-staging-mv.png b/website/docs/img/20210424-staging-mv.png
new file mode 100644
index 0000000..a83f98d
--- /dev/null
+++ b/website/docs/img/20210424-staging-mv.png
diff --git a/website/docs/img/20210425-alias-tree.png b/website/docs/img/20210425-alias-tree.png
new file mode 100644
index 0000000..d65aca9
--- /dev/null
+++ b/website/docs/img/20210425-alias-tree.png
diff --git a/website/docs/img/20210425-help-filter-stage.png b/website/docs/img/20210425-help-filter-stage.png
new file mode 100644
index 0000000..623e2df
--- /dev/null
+++ b/website/docs/img/20210425-help-filter-stage.png
diff --git a/website/docs/img/20210425-sdp.png b/website/docs/img/20210425-sdp.png
new file mode 100644
index 0000000..d7e4de1
--- /dev/null
+++ b/website/docs/img/20210425-sdp.png
diff --git a/website/docs/img/20210425-staging-filter.png b/website/docs/img/20210425-staging-filter.png
new file mode 100644
index 0000000..e1a7c32
--- /dev/null
+++ b/website/docs/img/20210425-staging-filter.png
diff --git a/website/docs/index.md b/website/docs/index.md
index 3337b0f..e5cdc22 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -1,5 +1,4 @@
 
-
 <p align=center style="max-width:600px">
 <img src="img/vache.svg" height=140px>
 <br><a class=install-link href=install>Install Broot</a>
@@ -28,7 +27,7 @@ Hit <kbd>alt</kbd><kbd>enter</kbd> and you're back to the terminal in the desire
 
 This way, you can navigate to a directory with the minimum amount of keystrokes, even if you don't exactly remember where it is.
 
-broot is fast and doesn't block (any keystroke interrupts the current search to start the next one).
+Broot is fast and doesn't block (any keystroke interrupts the current search to start the next one).
 
 Most useful keys for this:
 
@@ -44,7 +43,7 @@ Most useful keys for this:
 
 ![search](img/20210424-mycnf.png)
 
-broot tries to select the most relevant file. You can still go from one match to another one using <kbd>tab</kbd> or arrow keys.
+Broot tries to select the most relevant file. You can still go from one match to another one using <kbd>tab</kbd> or arrow keys.
 
 You may also search with a regular expression. To do this, add a `/` before the pattern.
 
@@ -115,11 +114,17 @@ You can add verbs or configure the existing ones; see [documentation](../conf_fi
 
 And you can add shortcuts, for example a <kbd>ctrl</kbd> sequence or a function key
 
+# Apply commands on several files
+
+Add files to the [staging area](../staging-area) then execute any command on all of them.
+
+![staging mv](img/20210424-staging-mv.png)
+
 # Replace `ls` (and its clones):
 
 If you want to display *sizes*, *dates* and *permissions*, do `br -sdp` which gets you this:
 
-![replace ls](img/20201130-sdp.png)
+![replace ls](img/20210425-sdp.png)
 
 You may also toggle options with a few keystrokes while inside broot. For example hitting a space, a `d` then enter shows you the dates. Or a space, then `h` then enter and you see hidden files.
 
diff --git a/website/docs/vim_mode.md b/website/docs/modal.md
index 7736193..7736193 100644
--- a/website/docs/vim_mode.md
+++ b/website/docs/modal.md
diff --git a/website/docs/staging-area.md b/website/docs/staging-area.md
new file mode 100644
index 0000000..4323c71
--- /dev/null
+++ b/website/docs/staging-area.md
@@ -0,0 +1,45 @@
+
+The staging area is broot's solution to let you execute commands on several files in one go.
+
+When the staging area is focused, commands apply to all the files it contains.
+
+# Stage and unstage files
+
+You can change the bindings to the `:stage`, `:unstage` and `:toggle_stage` verbs.
+The standard bindings are below
+
+verb | default binding | comment
+-|-|-
+`:toggle_stage` | <kbd>ctrl</kbd><kbd>g</kbd> | the easiest solution when not using broot in [modal](../modal)
+`:stage` | <kbd>+</kbd> | only in [command mode](../modal#usage)
+`:unstage` | <kbd>-</kbd> | only in [command mode](../modal#usage)
+`:clear_stage` |  | shortcut: `:cls`
+
+When staging a file, the staging area opens (but doesn't get focused) if it wasn't and there's not aleady the max number of panels open.
+
+# Execute a command
+
+Focus the staging area (usually with <kbd>ctrl</kbd><kbd>→</kbd>) then type the verb in the input.
+
+The verb will be executed, in order, to all files of the staging area.
+
+![staging mv](img/20210424-staging-mv.png)
+
+Computed groups which would have the same value for all files are shown in the status bar. For example here, when you type ` mv ../app-panels`, broot can tell you that it will run `mv {file} /home/dys/dev/broot/src/app-panels/` for each file of the staging area.
+
+Verbs which don't come back to broot after execution (for example `:cd` or any verb quitting broot) can't be executed this way.
+
+# Read the staging area
+
+The staging area can be opened or closed with the `:open_staging_area`, `:close_staging_area`, and `:toggle_staging_area` verbs, which have shortcuts `:osa`, `:csa`, and `:tsa`.
+But you rarely need those verbs as the staging area opens when you add to it and closes when it goes empty.
+
+You can filter, select, scroll, as in other panels. This may be convenient either to unstage a precise file from the staging area, or to check some files are present (or not) when there are many of them.
+
+![staging filter](img/20210425-staging-filter.png)
+
+# Evolutions
+
+The staging area is a new feature of broot. Some features (staging with globs for example) may be added, some may be changed, depending on your feedback.
+
+
diff --git a/website/docs/tricks.md b/website/docs/tricks.md
index 1b0ca16..61452a4 100644
--- a/website/docs/tricks.md
+++ b/website/docs/tricks.md
@@ -1,4 +1,18 @@
-# Use broot as a generic fuzzy finder
+# Replace tree
+
+This bash function gives you a better `tree` optimizing for the height of the screen:
+
+	function tree {
+	     br -c :pt "$@"
+	}
+
+![tree](img/20210425-alias-tree.png)
+
+This function supports most broot arguments:
+
+![tree with args](img/20201219-tree-with-args.png)
+
+# A generic fuzzy finder
 
 The goal here is to have a function you can use in shell to give you a path.
 
@@ -45,19 +59,6 @@ Here, the configuration file was used to ensure you can select a file with the e
 
 You may use the same configuration file to also specify colors to remember yourself you're not in a standard broot.
 
-# Replace tree
-
-This bash function gives you a better `tree` optimizing for the height of the screen:
-
-	function tree {
-	     br -c :pt "$@"
-	}
-
-![tree](img/20200710-alias-tree.png)
-
-This function supports most broot arguments:
-
-![tree with args](img/20201219-tree-with-args.png)
 
 # `dcd` : Deep fuzzy cd
 
diff --git a/website/docs/verbs.md b/website/docs/verbs.md
index 8600d56..285c832 100644
--- a/website/docs/verbs.md
+++ b/website/docs/verbs.md
@@ -5,6 +5,10 @@ The simplest verbs are just executed by typing a space (or `:`), then its first
 
 A verb can be related to the current selection. For example typing `:p` will execute the `:parent` verb, which focuses the parent of the selection (*focusing* a directory means making it the current root).
 
+Verbs are listed in help. As there are many of them, it can be sometimes useful to use pattern filtering to look at what's available for your concern. For example to see [stage](../staging-area) related verbs and their shortcuts:
+
+![help filter](img/20210425-help-filter-stage.png)
+
 # Verbs using the selection
 
 The `rm` verb executes the standard `rm` command.