Matchmaker

Matchmaker is fast, configurable and intuitive fuzzy searcher.

It takes inspiration from fzf in features and design, but reimagines the user experience. Built from the ground up in Rust, it brings a fully robust, modern and elegant search experience to the console.

Features

• Matching with nucleo.
• Fully configurable via a type-checked toml file. [^11]
• A minimal yet powerful syntax for overriding the configuration on the command line.
• Interactive preview supports color, scrolling, wrapping, multiple layouts, and even maximizing.
• Most of the familiar actions from fzf, as well as several new ones[^12].
• Mouse (location aware) scrolling! Horizontal scrolling! Grapheme-aware input wrapping!
• Extremely intelligent[^18] text wrapping and width sizing.
• Split input lines into multiple columns, that you can individually filter on (%col query^17), hide, and highlight.[^14]
• Split input lines by regex capture groups.
• Define Execute/Preview/Print/Accept actions with templates which safely inject the current item(s) (yes, columns are supported here too).
• All the dynamic UI support you could hope for: preview offsets, styled status lines, responsive header tables, wrapped footers, active and inactive column colors, stacked columns, multiple preview layouts[^15]... even overlays! (in the library).
• Bind keys to multiple actions, bind actions to mouse triggers, bind actions to event triggers, bind keys to rebind keys, bind keys to modify the configuration, bind keys to run a shell script and use its output to more keys, bind keys to set the header, footer, status, input, bind keys to semantic triggers, bind semantic triggers to actions, bind keys to -- wait nope thats about it.
• Comprehensive logging in case you need to debug applications.
• oh yeah, and mm --last-key gives you the last key that was pressed in a previous run of the program.[^13]
• Available as a rust library to use in your own code!

On the way:

• Matching with frizbee, a faster, typo-resistant matching algorithm.

[^11]: The benefits of a structured, hierarchical, global baseline configuration are many, including but not limited to the fact that toml strings make it much easier to bind keys to complex shell scripts.

[^12]: Custom exit codes, select all (CycleAll), PageUp/Down, Show Help, Cycle columns (NextColumn), Multiple input commands (ReloadNext), etc. ...

[^13]: This is useful for when you want to write a shell script that dispatches different actions on the output of matchmaker based on the key that was pressed.

[^14]: If no column names are configured, the autogenerated column names are sequential: 1, 2, 3...

[^15]: I like this so much i had to mention it twice

[^18]: There isn't a phd for text wrapping and width sizing, but if there was, I'd for sure claim it had one.

Installation

# requires cargo
cargo install matchmaker-cli

Or grab it from the releases page with extra features:

curl -fsSL https://raw.githubusercontent.com/Squirreljetpack/matchmaker/main/install.sh | sh

Pass it some items:

find . | mm

[!TIP] The default input and preview commands detect fd, bat and eza (otherwise falling back to ls and cat). Install them for a better experience!

Configuration

To begin, you can dump the default configuration to a file:

matchmaker --dump-config

The default locations are in order:

• ~/.config/matchmaker/config.toml (If the folder exists already).
• {PLATFORM_SPECIFIC_CONFIG_DIRECTORY}/matchmaker (Generally the same as above when on linux)

Matchmaker options are hierarchical, although most categories live at the top level:

[preview]
    show = true
    wrap = true
    header_lines = 3 # sticky the top 3 lines

# Full specification of (the default values of) a single layout. Multiple layouts can be specified.
[[preview.layout]]
    command    = ""
    side       = "right"
    percentage = 60
    min        = 30
    max        = 120

The structure of the config file is defined here[^1], and the full specification lives here[^2]. You can also view your current config using mm --dump-config | cat[^30].

Options can be overridden on the command line, where abbreviations are supported:

mm p.l "cmd=echo {}|||p=50|||max=20" cmd "ls" o "{=}"

# 1. Start mm with the following overrides:
# 2. List the contents of the current directory by executing `ls`
# 3. Show the current item name in the preview pane
# 4. Set a preferred percentage of 50 for the preview pane, but a column width of 20
# 5. Output the result without single quotes

[^1]: Note that the flatten attribute on the render field means that the subfields of RenderConfig should be specified at the top level of the toml (i.e. your toml should specify [results] instead of [render.results]).

[^2]: and parts of it here.

[^30]: Beware that without piping, this overwrites your config location with the default config!

Keybindings

Actions can be defined in your config.toml or on the command line.

The list of currently supported actions can be found here and here or from mm --doc binds.

To get the names of keys, type mm --test-keys.

In addition to keys, actions can also be bound to Events and Crossterm events (check your default config for details).

CLI

See here for the command-line syntax.

Matchmaker aims to achieve feature-parity with fzf (though not necessarily by the same means). If there's any specific feature that you'd like to see, open an issue!

Examples

Examples can be found here (toml files), and here (library use).

Currently, the first includes an example for interactively performing a full text search with ripgrep:

• Toggle between ripgrep and mm with ctrl-r
• The displayed preview autoscrolls to matched line: ? to toggle.
• Enter opens the file in your editor.
• Previous queries in each mode are stashed and restored upon switching.
• ctrl-. to cycle between columns.

# Try it yourself
mkdir -p ~/.config/matchmaker/presets
curl -L https://raw.githubusercontent.com/Squirreljetpack/matchmaker/main/matchmaker-cli/assets/rg.toml -o ~/.config/matchmaker/presets/rg.toml
mm --config ~/.config/matchmaker/presets/rg.toml

Migrating from fzf

Migrating from fzf to mm is conceptually straightforward because the two tools are almost fully feature-compatible. You can continue using familiar actions, like execute, and they will function the same way.

The main difference is syntax. For example, opening a selected file in your editor:

• In fzf:

fzf --bind "ctrl-o:execute($EDITOR {+})"

• In mm:

mm b.ctrl-o="Execute($EDITOR {+})"

[!NOTE] Note that templates can be named in matchmaker, but they only replace valid keys.

Here is a second demonstration, taken from zoxide.

• In fzf:

fzf \
  --bind=ctrl-z:ignore,btab:up,tab:down \
  --exact \
  --no-sort \
  --cycle \
  --keep-right \
  --border=sharp \
  --height=45% \
  --info=inline \
  --layout=reverse \
  --tabstop=1 \
  --exit-0

• In mm:

mm \
  binds.Shift-BackTab=Up \
  binds.BackTab=Up \
  binds.Tab=Down \
  matcher.sort_threshold=0 \
  results.scroll_wrap=true \
  results.wrap=false \
  results.autoscroll.end=true \
  results.autoscroll.context=0 \
  ui.border.type=Plain \
  tui.percentage=45 \
  results.reverse=true \
  exit.abort_empty=true

# Notes:
# - in mm, results.scroll_wrap is by default true, while results.wrap = true is included in the default config.
# - in mm --multi (from fzf) is always true. It can be disabled by not binding the Select actions, as is done here
# - matcher.sort_threshold is not available on the cargo version and requires the installer.
# - results.autoscroll.context=0 is a setting which does not appear in fzf but which is 4 by default in mm.

• In mm using aliases (and omitting defaults):

mm m.sort=0 ui.border.type=Plain tui.p=45 r.r= r.w=false \
b.Shift-BackTab=Up b.BackTab=Up b.Tab=Down

For quick reference, mm --doc provides fairly readable and comprehensive guides to various topics.

Library

Matchmaker can also be used as a library.

cargo add matchmaker

Example

Here is how to use Matchmaker to select from a list of strings.

use matchmaker::nucleo::{Indexed, Worker};
use matchmaker::{MatchError, Matchmaker, Result, Selector};

#[tokio::main]
async fn main() -> Result<()> {
    let items = vec!["item1", "item2", "item3"];

    let worker = Worker::new_single_column();
    worker.append(items);
    let selector = Selector::new(Indexed::identifier);
    let mm = Matchmaker::new(worker, selector);

    match mm.pick_default().await {
        Ok(v) => {
            println!("{}", v[0]);
        }
        Err(err) => match err {
            MatchError::Abort(1) => {
                eprintln!("cancelled");
            }
            _ => {
                eprintln!("Error: {err}");
            }
        },
    }

    Ok(())
}

For more information, check out the examples and Architecture.md

See also

• junegunn/fzf
• helix-editor/nucleo
• ratatui
• Canop/crokey
• skim-rs/skim
• autobib/nucleo-picker
• alexpasmantier/television
• helix-editor/helix