Queries
As you type in the prompt, Matchmaker parses your query into per-column patterns and scores every row concurrently across all active matcher threads.
Matching backends and scoring
Matchmaker supports two fuzzy matching backends under [matcher]:
nucleo(default): Subsequence fuzzy matching with smart case (case-insensitive unless a query token contains an uppercase letter), Unicode normalization (normalize), bonuses for consecutive characters and word starts, and optional prefix and path matching modes.frizbee(matcher.backend = "frizbee"): Typo-tolerant matching controlled bymax_typosand configurable match/penalty weights under[matcher].
Within any column query, space-separated tokens combine with logical AND. Individual tokens accept fzf-style operators:
| Token | Match condition |
|---|---|
abc | Fuzzy subsequence match |
'abc | Exact substring match |
^abc | Prefix match at the start of the column |
abc$ | Suffix match at the end of the column |
^abc$ | Exact full-column match |
!abc | Exclusion of rows matching abc |
foo\ bar | Literal space inside a single token |
See Other for operator examples and Options for [matcher] configuration.
Column filtering and focus
When rows are split into multiple columns (Input and data sources), a single query can filter several columns at once using %col selectors:
main %path src/ %ext .rs !mod- Primary column: Any query text before the first
%coltoken filters the primary column (columns.default, which defaults to the first column). %colprefix matching: A word starting with%switches the target column for the tokens that follow. You only need to type a prefix—%pselects the shortest column name starting withp(such aspath). Whencolumns.namesis unset, columns are named1throughcolumns.max, so%1,%2, and so on target them by number.- Unmatched
%tokens: If the name after%does not match the prefix of any column, the token is treated as literal search text in the current column. Escape a leading percent sign with\%. - Repeated selectors: Naming the same column more than once in a query appends the new terms to that column's pattern separated by a space.
- Cross-column options (
columns.names[].options): SettingOrUseDefaulton a column causes it to match against the primary column's query whenever no explicit%colpattern is given for it. SettingOptionalprevents a non-match in that column from rejecting the row when other columns also have active patterns.
Active column focus
The active column is the column owning the query span under your text cursor: if the cursor rests inside a %path ... segment, path is active; if the cursor is before any %col selector, the primary column is active.
Active column focus controls four things in the interface:
- Highlighting: The active column is drawn with
results.current_styleandresults.prefix_style, while other columns useresults.inactive_styleandresults.inactive_current_style(according toresults.row_connection). - Template expansion: The
{!},{=!},{+!}, and{-!}placeholders resolve to the active column of the current or selected rows (Template). - Keyboard navigation:
NextColumn(alt-./ctrl-.) andPrevColumn(alt-shift-./ctrl-shift-.) cycle focus across visible columns by appending%<col>to the query (replacing a trailing bare%colselector if you have not typed a pattern after it).SwitchColumn(col)focuses a specific column by name. - Column actions:
HideColumn,ExpandColumn,ShrinkColumn,Sort, andSortNumericact on the active column when invoked without an explicit column argument.
Visibility, widths, and scrolling
Matchmaker sizes visible columns automatically to fit their content and the terminal width, and lets you hide, resize, wrap, or scroll columns interactively:
| Action | Default keys | Effect |
|---|---|---|
HideColumn([col]) | alt-\ | Hides col or the active column (the primary column cannot be hidden) |
UnhideColumn([col]) | alt-shift-\ | Restores col or the most recently hidden column |
ExpandColumn([n]) | alt-= | Widens the active column (or 0-based visible column n) by 1 cell |
ShrinkColumn([n]) | alt-hyphen | Narrows the active column (or 0-based visible column n) by 1 cell |
ToggleWrap | alt-w | Toggles line wrapping for result rows (results.wrap) |
ToggleHeaderWrap | alt-w | Toggles line wrapping for header rows (header.wrap) |
HScroll(n) | alt-left / alt-right, alt-shift-left / alt-shift-right | Scrolls result cells horizontally by n cells (0 resets) |
VScroll(n) | alt-up / alt-down, alt-shift-up / alt-shift-down | Scrolls vertically inside multi-line result rows (0 resets) |
- Hidden columns: Columns can start hidden via
columns.names[].hidden = trueor be hidden at runtime withHideColumn. Hiding the currently focused column strips its trailing%colselector from the query. Hidden columns are omitted from{..}visible-range templates (Template) but remain accessible by name or index (such as{2}or{id}) and can still be queried by typing%name. - Width allocation and mouse dragging: Initial column widths can be seeded with
results.width_overridesand bounded byresults.min_width(see Options). Whenresults.column_spacingis non-zero (default1), dragging the spacing gutter between two columns with the mouse resizes the left column in place. - Multi-line rows and stacked layout:
results.max_height(0for unlimited) caps the rendered height of wrapped or multi-line rows;VScrollscrolls through clipped lines on the current row. Settingresults.vertical = true(r.v, aliasstacked_columns) renders each row's visible columns stacked vertically on consecutive lines instead of side by side. - Horizontal autoscroll: When
results.autoscroll.enabledistrue(default), unwrapped columns automatically pan horizontally to keep matched characters in view around the match. Moving the selection cursor to another row resets manualHScrollandVScrolloffsets.
Sorting results
By default, rows are ranked by fuzzy match score, with ties broken by arrival order. You can adjust score stability or sort rows by any column at startup (matcher.sort, CLI alias S) or at runtime:
| Action | Default keys | Effect |
|---|---|---|
Sort([n]) | alt-s | Ascending lexicographic sort on the active column (or 0-based displayed column n), or toggle off |
SortNumeric([n]) | alt-n | Ascending numeric sort (integers and decimals before text) on the active or n-th displayed column, or toggle off |
SortReverse([bool]) | alt-r | Direction toggle (or explicit set) for base item order and active column sorts |
SortThreshold([n]) | (unbound) | Matcher score-stability threshold set to n (omitted restores maximum stability) |
- Toggling column sorts: Triggering
SortorSortNumericoverrides score ranking (SortThresholdis raised to maximum stability) and orders all matched rows by the target column. Pressing the same sort key again on the same column turns the column sort off and restores the configuredmatcher.sort.threshold. - Score stability (
matcher.sort.threshold, CLI aliast): Controls how much a higher fuzzy score must beat an earlier item's score to overtake it.0(ortrue) always sorts strictly by match score, positive integers require that minimum score difference before reordering, andfalsesets the maximum threshold to keep items in their input order regardless of score differences.
Pausing internal filtering
To decouple the query bar from the built-in matcher—for example, when re-running an external search tool like rg on QueryChange—trigger Filtering(false) to pause internal refiltering and Filtering(true) (or Filtering with no argument) to resume it.