Document use of filter columns in pickers (helix-editor#11218)

* Document use of filter columns in pickers. Filtering on columns was implemented in helix-editor#9647. The only documentation I could find on this feature was the PR itself, and the video demo used a different syntax. * Note that column filters are space-separated. * Note that picker filters can be abbreviated. * Specify correct picker in docs. * Clarify picker filter prefix shortenting. Co-authored-by: Michael Davis <mcarsondavis@gmail.com> * Move picker docs to their own section. * Update book/src/pickers.md Co-authored-by: Michael Davis <mcarsondavis@gmail.com> * Improve docs on picker registers, keybinds, and syntax. * Clarify wording around picker queries. Co-authored-by: Michael Davis <mcarsondavis@gmail.com> --------- Co-authored-by: Ryan Roden-Corrent <ryan@rcorre.net> Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
stackotter · Aug 28, 2024 · 867d41d · 867d41d
1 parent ac9d66a
commit 867d41d
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 0 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -10,6 +10,7 @@
   - [Surround](./surround.md)
   - [Textobjects](./textobjects.md)
   - [Syntax aware motions](./syntax-aware-motions.md)
+  - [Pickers](./pickers.md)
   - [Keymap](./keymap.md)
   - [Commands](./commands.md)
   - [Language support](./lang-support.md)

diff --git a/book/src/keymap.md b/book/src/keymap.md
@@ -436,6 +436,8 @@ you to selectively add search terms to your selections.
 ## Picker
 
 Keys to use within picker. Remapping currently not supported.
+See the documentation page on [pickers](./pickers.md) for more info.
+[Prompt](#prompt) keybinds also work in pickers, except where they conflict with picker keybinds.
 
 | Key                          | Description                                                |
 | -----                        | -------------                                              |

diff --git a/book/src/pickers.md b/book/src/pickers.md
@@ -0,0 +1,11 @@
+## Using pickers
+
+Helix has a variety of pickers, which are interactive windows used to select various kinds of items. These include a file picker, global search picker, and more. Most pickers are accessed via keybindings in [space mode](./keymap.md#space-mode). Pickers have their own [keymap](./keymap.md#picker) for navigation.
+
+### Filtering Picker Results
+
+Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegunn/fzf?tab=readme-ov-file#search-syntax). Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the LSP. Note that OR operations (`|`) are not currently supported.
+
+If a picker shows multiple columns, you may apply the filter to a specific column by prefixing the column name with `%`. Column names can be shortened to any prefix, so `%p`, `%pa` or `%pat` all mean the same as `%path`. For example, a query of `helix %p .toml$ !lang` in the global search picker searches for the term "helix" within files with paths ending in ".toml" but not including "lang".
+
+You can insert the contents of a [register](./registers.md) using `Ctrl-r` followed by a register name. For example, one could insert the currently selected text using `Ctrl-r`-`.`, or the directory of the current file using `Ctrl-r`-`%` followed by `Ctrl-w` to remove the last path section. The global search picker will use the contents of the [search register](./registers.md#default-registers) if you press `Enter` without typing a filter. For example, pressing `*`-`Space-/`-`Enter` will start a global search for the currently selected text.