From ea2cb65942b8641855826c031b497613ca5ae629 Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Wed, 17 Jul 2024 20:43:28 -0400 Subject: [PATCH 1/9] 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. --- book/src/keymap.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/book/src/keymap.md b/book/src/keymap.md index 402b83ef7527..777c06edaca4 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -452,6 +452,10 @@ Keys to use within picker. Remapping currently not supported. | `Ctrl-t` | Toggle preview | | `Escape`, `Ctrl-c` | Close picker | +In pickers, you can filter specific columns by prefixing the column name with `%`. +For example, in the file picker, `init %path .proto` searches for files ending +in ".proto" containing the text "init". + ## Prompt Keys to use within prompt, Remapping currently not supported. From 86e6e6dfafbd41ca8cf4d820474a7dbeb9154170 Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Thu, 18 Jul 2024 06:21:14 -0400 Subject: [PATCH 2/9] Note that column filters are space-separated. --- book/src/keymap.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index 777c06edaca4..368f7fd5b450 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -453,8 +453,10 @@ Keys to use within picker. Remapping currently not supported. | `Escape`, `Ctrl-c` | Close picker | In pickers, you can filter specific columns by prefixing the column name with `%`. -For example, in the file picker, `init %path .proto` searches for files ending -in ".proto" containing the text "init". +All words after a `%` term are treated as filters for that column. +The base filter is a regex, while column filters are a space-separated of literals. +For example, in the file picker, `init %path api .proto` searches for files containing +the text "init", whose filenames contain "api" and ".proto". ## Prompt From 2aa831e9b6c089c16cb396502be61cbe2a6e33ce Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Thu, 18 Jul 2024 08:16:28 -0400 Subject: [PATCH 3/9] Note that picker filters can be abbreviated. --- book/src/keymap.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/src/keymap.md b/book/src/keymap.md index 368f7fd5b450..f1080c5ece1e 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -457,6 +457,7 @@ All words after a `%` term are treated as filters for that column. The base filter is a regex, while column filters are a space-separated of literals. For example, in the file picker, `init %path api .proto` searches for files containing the text "init", whose filenames contain "api" and ".proto". +Column names can be abbreviated, so `%p` means the same as `%path`. ## Prompt From 033d5fa0d7e75a0ff41ce9ddc288d26ef577961b Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Thu, 18 Jul 2024 10:15:04 -0400 Subject: [PATCH 4/9] Specify correct picker in docs. --- book/src/keymap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index f1080c5ece1e..d9c7cf70979a 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -455,7 +455,7 @@ Keys to use within picker. Remapping currently not supported. In pickers, you can filter specific columns by prefixing the column name with `%`. All words after a `%` term are treated as filters for that column. The base filter is a regex, while column filters are a space-separated of literals. -For example, in the file picker, `init %path api .proto` searches for files containing +For example, in the global search picker, `init %path api .proto` searches for files containing the text "init", whose filenames contain "api" and ".proto". Column names can be abbreviated, so `%p` means the same as `%path`. From fe337b4bc9e65add5085167f5074e45470258c37 Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Thu, 18 Jul 2024 12:04:51 -0400 Subject: [PATCH 5/9] Clarify picker filter prefix shortenting. Co-authored-by: Michael Davis --- book/src/keymap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index d9c7cf70979a..7f2356e86ec9 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -457,7 +457,7 @@ All words after a `%` term are treated as filters for that column. The base filter is a regex, while column filters are a space-separated of literals. For example, in the global search picker, `init %path api .proto` searches for files containing the text "init", whose filenames contain "api" and ".proto". -Column names can be abbreviated, so `%p` means the same as `%path`. +Column names can be shortened to any prefix, so `%p`, `%pa` or `%pat` all mean the same as `%path`. ## Prompt From 85066a71fa3e478cbae284ddbcea6ff19393584d Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Fri, 19 Jul 2024 06:36:38 -0400 Subject: [PATCH 6/9] Move picker docs to their own section. --- book/src/SUMMARY.md | 1 + book/src/keymap.md | 8 +------- book/src/pickers.md | 11 +++++++++++ 3 files changed, 13 insertions(+), 7 deletions(-) create mode 100644 book/src/pickers.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 027b885a8e84..e6be2ebc01b7 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 7f2356e86ec9..fe4905971681 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -436,6 +436,7 @@ 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. | Key | Description | | ----- | ------------- | @@ -452,13 +453,6 @@ Keys to use within picker. Remapping currently not supported. | `Ctrl-t` | Toggle preview | | `Escape`, `Ctrl-c` | Close picker | -In pickers, you can filter specific columns by prefixing the column name with `%`. -All words after a `%` term are treated as filters for that column. -The base filter is a regex, while column filters are a space-separated of literals. -For example, in the global search picker, `init %path api .proto` searches for files containing -the text "init", whose filenames contain "api" and ".proto". -Column names can be shortened to any prefix, so `%p`, `%pa` or `%pat` all mean the same as `%path`. - ## Prompt Keys to use within prompt, Remapping currently not supported. diff --git a/book/src/pickers.md b/book/src/pickers.md new file mode 100644 index 000000000000..3e801be5c330 --- /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. + +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, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang". + +Note that the [current selection register](./registers.md#special-registers) can be used to insert the text of the current selection using `Ctrl-r`-`.`. In addition, the global search picker will use the contents of the [search register](./registers.md#special-registers) if you press `Enter` without typing a filter. For example, pressing `*`-`Space-/`-`Enter` will start a global search for the currently selected text. From 8aa5f3fc2bf75b42ad0dae1e565074b8cfa7d7ef Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Sat, 20 Jul 2024 07:42:58 -0400 Subject: [PATCH 7/9] Update book/src/pickers.md Co-authored-by: Michael Davis --- book/src/pickers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/pickers.md b/book/src/pickers.md index 3e801be5c330..6277612a9a40 100644 --- a/book/src/pickers.md +++ b/book/src/pickers.md @@ -8,4 +8,4 @@ Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegu 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, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang". -Note that the [current selection register](./registers.md#special-registers) can be used to insert the text of the current selection using `Ctrl-r`-`.`. In addition, the global search picker will use the contents of the [search register](./registers.md#special-registers) if you press `Enter` without typing a filter. For example, pressing `*`-`Space-/`-`Enter` will start a global search for the currently selected text. +Note that the [current selection register](./registers.md#special-registers) can be used to insert the text of the current selection using `Ctrl-r`-`.`. In addition, 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. From 9c020e97c372e030b899a5206dbbf7b2a7406809 Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Sat, 20 Jul 2024 08:02:52 -0400 Subject: [PATCH 8/9] Improve docs on picker registers, keybinds, and syntax. --- book/src/keymap.md | 1 + book/src/pickers.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/book/src/keymap.md b/book/src/keymap.md index fe4905971681..0e60f28262cb 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -437,6 +437,7 @@ you to selectively add search terms to your selections. 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 index 6277612a9a40..33b423b3ab0f 100644 --- a/book/src/pickers.md +++ b/book/src/pickers.md @@ -4,8 +4,8 @@ Helix has a variety of pickers, which are interactive windows used to select var ### 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. +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, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang". -Note that the [current selection register](./registers.md#special-registers) can be used to insert the text of the current selection using `Ctrl-r`-`.`. In addition, 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. +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. From 64d4c8babfbbdc6b73a550ea04621e9b083bf2f7 Mon Sep 17 00:00:00 2001 From: Ryan Roden-Corrent Date: Tue, 23 Jul 2024 15:23:39 -0400 Subject: [PATCH 9/9] Clarify wording around picker queries. Co-authored-by: Michael Davis --- book/src/pickers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/pickers.md b/book/src/pickers.md index 33b423b3ab0f..993d71466cbe 100644 --- a/book/src/pickers.md +++ b/book/src/pickers.md @@ -6,6 +6,6 @@ Helix has a variety of pickers, which are interactive windows used to select var 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, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang". +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.