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.