From 5d3f05cbe148fce050cab40aa9e718dd8917258c Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Wed, 24 Jul 2024 12:25:00 -0400 Subject: [PATCH] Document use of filter columns in pickers (#11218) * Document use of filter columns in pickers. Filtering on columns was implemented in #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 * Move picker docs to their own section. * Update book/src/pickers.md Co-authored-by: Michael Davis * Improve docs on picker registers, keybinds, and syntax. * Clarify wording around picker queries. Co-authored-by: Michael Davis --------- Co-authored-by: Ryan Roden-Corrent Co-authored-by: Michael Davis --- book/src/SUMMARY.md | 1 + book/src/keymap.md | 2 ++ book/src/pickers.md | 11 +++++++++++ 3 files changed, 14 insertions(+) create mode 100644 book/src/pickers.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 027b885a..e6be2ebc 100644 --- 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 index 402b83ef..0e60f282 100644 --- 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 new file mode 100644 index 00000000..993d7146 --- /dev/null +++ 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.