PICKERS.md

Pickers

This page documents the builtin picker modules. Each picker lives in its own module under fuzzy.pickers.*. The APIs are intentionally small, but the behavior is rich. The pickers are designed to be performant by default and avoid expensive transforms up front. Matching happens on the content you provide. Display and decoration are used for extra context without altering the matching corpus.

Each section below explains what the picker does, what its options mean, how those options change behavior, and when certain options are or are not suitable. Examples are included as a quick reference, but the primary focus here is descriptive guidance.

Contents

• Pickers
  • Contents
  • Git
    • Git Files
    • Git Status
    • Git Branches
    • Git Commits
    • Git Buffer Commits
    • Git Stash
  • Files
    • Files
    • Oldfiles
  • Buffers
    • Buffers
    • Tabs
  • Lines
    • Lines (All Buffers)
    • Lines (Current Buffer)
  • Grep
    • Grep
    • Grep Word
    • Grep Visual
  • Lists
    • Quickfix
    • Location List
    • Quickfix Stack
    • Location List Stack
  • Editor
    • Commands
    • Keymaps
    • Registers
    • Marks
    • Jumps
    • Changes
    • Command History
    • Search History
    • Colorscheme
    • Spell Suggest
  • Help
    • Helptags
    • Manpages
    • Vimdoc
  • Tags
    • Tags
    • Buffer Tags
  • Registry

Git

The Git pickers are built around git commands and stream their output. They are designed for repositories of any size while keeping UI latency low by batching and debouncing. All of them accept the standard picker options (preview, icons, stream and match steps), and then add Git-specific knobs.

All git pickers also accept:

• watch (default false): enables a lightweight git-state tick to refresh results on reopen.

Git Files

Lists files from the current git repository. The matcher uses the file path as the content, while the display layer adds icons, path shortening, and visual separators.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_files({
    cwd = vim.uv.cwd,
    untracked = true,
    preview = true,
    icons = true,
    stream_step = 100000,
    match_step = 75000,
})

Options and behavior:

• cwd: Controls where the git command is executed. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). If you work in nested repositories, pass the root to avoid confusing output.

• untracked: Includes untracked files in addition to tracked files. This is useful for new files during development. It is less suitable when you want a clean list of tracked files only.

• preview: If enabled, a file previewer is created. The preview is lazy and only materializes for the selection, so it does not inflate memory usage.

• icons: Adds file icons. Display only.

• stream_step, match_step: Higher values process more items per iteration. Use lower values if you notice UI hitching on extremely large repos.

Git Status

Lists git status --porcelain entries. The raw status line is preserved as content, and the display layer expands it into a readable line with filename and status hint. This is the right picker when you want quick triage of a working tree.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_status({
    cwd = vim.uv.cwd,
    preview = true,
    icons = true,
    stream_step = 50000,
    match_step = 50000,
})

Options and behavior:

• cwd: This can be a string path, a function returning a path, or true to use vim.uv.cwd(). It must resolve inside a repository. The picker asserts if a repo root cannot be found.

• preview: Previews the selected file if the status entry can be mapped to a path.

• icons: Adds file icons. Display only.

• stream_step, match_step: Tune for very large status lists, usually unnecessary unless you have a massive working tree with many untracked files.

Git Branches

Lists local and remote branches, sorted by committer date. Use this as a fast branch switcher and as a quick way to discover recently updated branches.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_branches({
    cwd = vim.uv.cwd,
    stream_step = 50000,
    match_step = 50000,
})

Options and behavior:

• cwd: Repository root, a path inside the repo, a function returning one of those, or true to use vim.uv.cwd().

• stream_step, match_step: For very large repos with many branches, lowering these values can smooth UI.

Git Commits

Lists commits for the repository. The match content includes the commit hash and subject so searching by hash fragment or message works naturally.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_commits({
    cwd = vim.uv.cwd,
    stream_step = 50000,
    match_step = 50000,
})

Options and behavior:

• cwd: Repository root, a path inside the repo, a function returning one of those, or true to use vim.uv.cwd(). If you are inside a submodule, pass its root explicitly to avoid ambiguity.

• stream_step, match_step: Useful only for repos with very long histories.

Git Buffer Commits

Lists commits for the current buffer file. This is meant to answer “when did this change” and is optimized for file history.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_bcommits({
    stream_step = 50000,
    match_step = 50000,
})

Options and behavior:

• Uses the current buffer path as input. If the buffer has not been written to disk, the picker will assert.

• cwd: Optional repository root override. This can be a string path, a function returning a path, or true to use vim.uv.cwd().

• stream_step, match_step behave as above.

Git Stash

Lists stash entries. The match content includes stash ref and subject. This is optimized for inspection and quick selection, not for bulk stash manipulation.

local git_picker = require("fuzzy.pickers.git")

git_picker.open_git_stash({
    cwd = vim.uv.cwd,
    stream_step = 50000,
    match_step = 50000,
})

Options and behavior:

• cwd: This can be a string path, a function returning a path, or true to use vim.uv.cwd(). It should resolve inside a repository.

• Use this picker when you need fast stash inspection. It is not ideal for bulk stash manipulation since actions are intentionally minimal.

Files

File-related pickers are tuned for performance and minimal allocations. They use display helpers and decorators to enrich the list while keeping matching stable.

Files

Lists files using rg, fd, or find (first available). This is the primary files picker and the most common entry point.

local files_picker = require("fuzzy.pickers.files")

files_picker.open_files_picker({
    cwd = vim.uv.cwd,
    hidden = true,
    follow = false,
    no_ignore = false,
    no_ignore_vcs = false,
    preview = true,
    icons = true,
    stream_step = 100000,
    match_step = 75000,
})

Options and behavior:

• cwd: Root for the file scan. This can be a string path, a function returning a path, or true to use vim.uv.cwd().

• watch (default false): Enables a filesystem tick to refresh results on reopen.

• hidden: Include hidden files. Recommended when working with dotfiles or config directories, not always ideal in large repos where hidden folders contain huge caches.

• follow: Follow symlinks. Use with caution if you have symlink loops.

• no_ignore, no_ignore_vcs: Bypass ignore rules. This is helpful for debugging or searching vendor trees, but it can drastically increase the number of results.

• preview, icons: Display only.

• stream_step, match_step: Tune for large trees. Lower these if you see stutter.

Oldfiles

Lists :oldfiles entries. Matching is done on the file path, while display can shorten and decorate the line.

local oldfiles_picker = require("fuzzy.pickers.oldfiles")

oldfiles_picker.open_oldfiles_picker({
    cwd = vim.uv.cwd,
    max = 256,
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
    preview = true,
    icons = true,
})

Options and behavior:

• cwd: Base directory for filtering and path display. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). When set, only entries under cwd are included.

• max: Limit the number of entries emitted from :oldfiles. The default is 256.

• filename_only, path_shorten, home_to_tilde: Path display helpers.

• preview, icons: Display only.

Buffers

Buffer pickers use buffer entries with filename metadata. Matching is performed on the display text.

Buffers

Lists buffers with filtering and optional sorting. This is optimized to avoid unnecessary string creation up front, while still letting the matcher filter by filename.

local buffers_picker = require("fuzzy.pickers.buffers")

buffers_picker.open_buffers_picker({
    current_tab = false,
    show_unlisted = false,
    show_unloaded = false,
    include_special = false, -- false | true | { "terminal", "quickfix" } | { terminal = true }
    ignore_current_buffer = true,
    sort_lastused = true,
    cwd = vim.uv.cwd,
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
    preview = true,
    icons = true,
})

Options and behavior:

• current_tab: Restrict results to buffers visible in the current tab. Useful for focused workflows, less suitable when you want global navigation.

• show_unlisted, show_unloaded: Include unlisted or unloaded buffers. Use these when you need a full buffer inventory; otherwise keep them off for cleaner lists.

• include_special: Controls special buftype entries.

  • false: only normal buffers (buftype == "").
  • true: include all special buftypes.
  • table: include only listed buftypes, as either an array ({ "terminal", "quickfix" }) or a map ({ terminal = true }).

• ignore_current_buffer: Exclude the active buffer. Useful when you are looking for a jump target.

• sort_lastused: Sort buffers by recent use with current and alternate buffers pinned at the top. Disable if you want raw buffer order.

• cwd: Base directory for filtering and path display. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). When set, only buffers under cwd are included.

• filename_only: Display just the filename, not the full path.

• path_shorten, home_to_tilde: Path display helpers. They do not affect matching.

• preview, icons: Display only.

Tabs

Lists open tabpages. Content uses tab numbers and buffer names. The display favors a concise summary rather than full buffer details, giving you a lightweight overview of which files are visible in each tab.

local tabs_picker = require("fuzzy.pickers.tabs")

tabs_picker.open_tabs_picker({
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
})

Options and behavior:

• filename_only: Display just the filename for the first window in each tab.

• path_shorten, home_to_tilde: Path display helpers for the tab filename summary.

Lines

Line pickers prioritize keeping memory usage low while keeping matching accurate. Line text is available on entries for display and matching.

Lines (All Buffers)

Lists lines across buffers. Text is fetched lazily for display, while content uses buffer and line references for matching. This is ideal when you want to search across many files without creating huge strings up front.

local lines_picker = require("fuzzy.pickers.lines")

lines_picker.open_lines_picker({
    show_unlisted = false,
    show_unloaded = false,
    ignore_current_buffer = false,
    cwd = vim.uv.cwd,
    include_special = false, -- false | true | { "terminal", "quickfix" } | { terminal = true }
    preview = false,
    match_step = 50000,
})

Options and behavior:

• show_unlisted, show_unloaded: Include buffers that are not normally visible. This is useful for global searches but increases the total item count.

• ignore_current_buffer: Excludes the active buffer from the line list.

• cwd: This can be a string path, a function returning a path, or true to use vim.uv.cwd(). When set, only buffers under cwd are included.

• include_special: Controls special buftype entries.

  • false: only normal buffers (buftype == "").
  • true: include all special buftypes.
  • table: include only listed buftypes, as either an array ({ "terminal", "quickfix" }) or a map ({ terminal = true }).

• preview: Previewing full lines can be redundant; keep off unless you add a custom previewer.

• match_step: Tune if you are working in a large codebase with very large buffers.

Word and visual variants pre-fill the prompt with <cword> or the visual selection.

local lines_picker = require("fuzzy.pickers.lines")

lines_picker.open_lines_word({
    match_step = 50000,
})

lines_picker.open_lines_visual({
    match_step = 50000,
})

Lines (Current Buffer)

Lists lines in the current buffer only. This is the quick “jump to line” workflow that stays fast even on very large files because content stays minimal.

local blines_picker = require("fuzzy.pickers.blines")

blines_picker.open_blines_picker({
  preview = false,
  match_step = 50000,
})

Options and behavior:

• preview: Usually unnecessary for current-buffer lines.

Word and visual variants pre-fill the prompt with <cword> or the visual selection.

local blines_picker = require("fuzzy.pickers.blines")

blines_picker.open_buffer_lines_word({
    match_step = 50000,
})

blines_picker.open_buffer_lines_visual({
    match_step = 50000,
})

Grep

The grep picker is first-class. It is interactive, debounced, and can re-run the underlying command as the query changes. This is the right choice for fast project searches without the overhead of external fuzzy tools.

Grep

Interactive grep using rg or grep (first available). Supports query -- args parsing when rg_glob is enabled.

local grep_picker = require("fuzzy.pickers.grep")

grep_picker.open_grep_picker({
    cwd = vim.uv.cwd,
    hidden = false,
    follow = false,
    no_ignore = false,
    no_ignore_vcs = false,
    rg_glob = true,
    rg_glob_fn = nil,
    glob_flag = "--iglob",
    glob_separator = "%s%-%-",
    rg_opts = "--hidden --column --line-number --no-heading --color=never --smart-case",
    grep_opts = "-n -H -r --line-buffered",
    RIPGREP_CONFIG_PATH = vim.env.RIPGREP_CONFIG_PATH,
    preview = true,
    icons = true,
    stream_step = 25000,
    match_step = 25000,
    prompt_debounce = 200,
})

Options and behavior:

• cwd: Search root. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). This matters for performance and accuracy, especially in monorepos.

• watch (default false): Enables a filesystem tick to refresh results on reopen.

• hidden, follow, no_ignore, no_ignore_vcs: Pass-through flags to the underlying command. These can drastically change result volume, so use them deliberately.

• rg_glob: Enables the query -- args form. When true, the picker splits the input into two parts: the regex query and extra arguments that are passed back to the command. This is ideal for ad hoc globbing and exclusions during interactive use. If you do not need dynamic args, disable it for simpler input.

• rg_glob_fn: Custom split logic. It receives the raw query and returns two values: (regex, args). args can be a string, a list, or nil. Use this if you need a different separator, or if you want to parse custom flags. The picker uses your returned args verbatim when re-running the grep.

• glob_flag, glob_separator: Convenience helpers for the default rg_glob parser. glob_separator defines the split point (default matches " --"), and glob_flag is used when you convert glob fragments into arguments.

• rg_opts, grep_opts: Startup arguments for the command. These can be either a whitespace-delimited string or a list of arguments. Keep them aligned with your expectations for case sensitivity and regex engine.

• RIPGREP_CONFIG_PATH: Allows the picker to respect your ripgrep config even when the shell environment is not sourced.

• preview, icons: Display only.

• stream_step, match_step: Lower these to keep UI responsive while typing with extremely large result sets.

• prompt_debounce: Controls how quickly the grep is re-run as you type. Lower values are more responsive but may re- run too often.

Grep Word

Same as the main grep picker, but the prompt is prefilled with <cword>.

local grep_picker = require("fuzzy.pickers.grep")

grep_picker.open_grep_word({
    cwd = vim.uv.cwd,
})

Grep Visual

Same as the main grep picker, but the prompt is prefilled with the visual selection.

local grep_picker = require("fuzzy.pickers.grep")

grep_picker.open_grep_visual({
    cwd = vim.uv.cwd,
})

Lists

Quickfix and location list pickers use the list entries as content but keep display lightweight. They are designed to avoid heavy per-entry processing.

Quickfix

Lists items from the quickfix list. Each entry shows file, line, column, and text while keeping the list entry as the match target so filtering remains fast.

local quickfix_picker = require("fuzzy.pickers.quickfix")

quickfix_picker.open_quickfix_picker({
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
    cwd = vim.uv.cwd,
    preview = true,
    icons = true,
    match_step = 50000,
})

Options and behavior:

• filename_only: Display just the filename rather than full path. Matching still uses the content from the list entry.

• path_shorten, home_to_tilde: Display helpers. These are not part of the match content.

• cwd: Base directory for filtering and path display. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). When set, only entries under cwd are included.

• preview, icons: Display only.

• match_step: For very large lists.

The visual variant pre-fills the prompt with the visual selection.

local quickfix_picker = require("fuzzy.pickers.quickfix")

quickfix_picker.open_quickfix_visual({
    preview = true,
})

Location List

Lists items from the current window location list, with the same display style as the quickfix picker but scoped to the active window.

local loclist_picker = require("fuzzy.pickers.loclist")

loclist_picker.open_loclist_picker({
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
    cwd = vim.uv.cwd,
    preview = true,
    icons = true,
    match_step = 50000,
})

Options and behavior:

• filename_only, path_shorten, home_to_tilde: Display helpers. These are not part of the match content.

• cwd: Base directory for filtering and path display. This can be a string path, a function returning a path, or true to use vim.uv.cwd(). When set, only entries under cwd are included.

• preview, icons, match_step: Same meaning as quickfix; tune for large lists.

The visual variant pre-fills the prompt with the visual selection.

local loclist_picker = require("fuzzy.pickers.loclist")

loclist_picker.open_loclist_visual({
    preview = true,
})

Quickfix Stack

Lists quickfix history entries. Each entry captures the list title and context so you can jump back to a previous quickfix state without rebuilding it.

local quickfix_stack_picker = require("fuzzy.pickers.quickfix_stack")

quickfix_stack_picker.open_quickfix_stack({
})

Location List Stack

Lists location list history entries for the current window. This mirrors the quickfix stack picker but keeps the scope local.

local loclist_stack_picker = require("fuzzy.pickers.loclist_stack")

loclist_stack_picker.open_loclist_stack({
})

Editor

Editor pickers expose built-in Neovim lists. These are intentionally light, focusing on fast filtering rather than heavy formatting.

Commands

Lists user commands. Each entry includes the command name; this works well as a command palette when combined with fuzzy search.

local commands_picker = require("fuzzy.pickers.commands")

commands_picker.open_commands_picker({
    include_builtin = true,
    include_user = true,
})

Options and behavior:

• include_builtin: Include built-in commands. Turn this on if you want a global command palette; leave it off for a smaller list focused on your config.

• include_user: Include user-defined commands.

Keymaps

Lists keymaps with their modes and descriptions. The picker balances readability and density so you can search for a mapping by its LHS or RHS without clutter.

local keymaps_picker = require("fuzzy.pickers.keymaps")

keymaps_picker.open_keymaps_picker({
    include_buffer = true,
    modes = { "n" },
    max_text = 120,
})

Options and behavior:

• include_buffer: Include buffer-local keymaps in addition to global mappings.

• modes: List of modes to include.

• max_text: Truncate RHS text to keep the list compact.

Registers

Lists registers and their contents. The display keeps the register name and a concise preview of its contents, which makes it easy to find the right register without loading full blobs into the match content.

local registers_picker = require("fuzzy.pickers.registers")

registers_picker.open_registers_picker({
    preview = true,
    filter = "^a$",
})

Options and behavior:

• filter: Pattern for register names to include. When set, only matching registers are listed.

• preview: Enable the preview window. The preview shows the full register contents, including multi-line values.

Marks

Lists marks with enough context to understand where each mark points. Each entry reflects the mark name, the buffer or file it belongs to, and the line and column where it lands. Local marks (like a to z) are scoped to a buffer, while global marks (like A to Z and numbered marks) can jump across files. This picker presents them in a compact form so you can filter by mark letter or by the file path, and still see the destination at a glance without loading more data up front.

local marks_picker = require("fuzzy.pickers.marks")

marks_picker.open_marks_picker({
    marks = "[a-z]",
    include_local = true,
    include_global = true,
    preview = true,
    icons = true,
})

Options and behavior:

• marks: Pattern of marks to include. Use lowercase ranges for local marks, uppercase ranges for global marks, or a combined pattern if you want both.

• include_local: Include buffer-local marks from the current buffer.

• include_global: Include global marks.

• preview, icons: Display only.

Jumps

Lists jump list entries. Each entry includes the target buffer or file and the recorded cursor position, so you can retrace navigation history quickly. The list favors brevity so it stays fast even when the jumplist is long.

local jumps_picker = require("fuzzy.pickers.jumps")

jumps_picker.open_jumps_picker({
    filename_only = false,
    path_shorten = nil,
    home_to_tilde = true,
    preview = false,
    icons = true,
})

Options and behavior:

• filename_only: Display just the filename rather than the full path.

• path_shorten, home_to_tilde: Path display helpers for jump entries.

• preview, icons: Display only.

Changes

Lists change list entries. Each entry represents a position where the buffer changed, so this picker is useful for stepping backward through recent edits.

local changes_picker = require("fuzzy.pickers.changes")

changes_picker.open_changes_picker({
    preview = false,
    icons = true,
})

Options and behavior:

• preview, icons: Display only.

Command History

Lists command history entries. This is a quick way to re-run or inspect previous : commands without digging through history manually.

local command_history_picker = require("fuzzy.pickers.command_history")

command_history_picker.open_command_history({
})

Search History

Lists search history entries. Use this to recall previous / or ? searches, especially when you want to reuse a complex regex.

local search_history_picker = require("fuzzy.pickers.search_history")

search_history_picker.open_search_history({
})

Colorscheme

Lists installed color schemes and lets you preview them. This is intentionally lightweight and only applies the theme to the UI when you change selection.

local colorscheme_picker = require("fuzzy.pickers.colorscheme")

colorscheme_picker.open_colorscheme_picker({
    preview = true,
})

Options and behavior:

• preview: Enable the preview window; selections are applied as you move. Use cautiously if you are sensitive to rapid theme changes.

Spell Suggest

Lists spell suggestions for the word under the cursor. The target word is resolved at open time, so canceling and reopening after moving the cursor refreshes suggestions for the new word. The list is small and focused, and matches by suggestion text so you can quickly filter close alternatives.

local spell_suggest_picker = require("fuzzy.pickers.spell_suggest")

spell_suggest_picker.open_spell_suggest({
    target_word_text = nil,
    suggest_limit_count = 25,
})

Options and behavior:

• target_word_text: Override the target word instead of using the word under cursor. When nil or empty, the picker uses <cword> on each open so suggestions stay in sync with the current cursor word.

• suggest_limit_count: Limit the number of suggestions. Use lower values for speed, higher values for completeness.

Help

Help pickers are intentionally simple and defer most work to Neovim’s help system.

Helptags

Lists helptags. Each entry is a help tag identifier.

local helptags_picker = require("fuzzy.pickers.helptags")

helptags_picker.open_helptags_picker({
})

Manpages

Lists man pages. Entries are collected from apropos -k . (fallback: man -k .) and normalized to name(section). The user is allowed to provide a list of additional customized arguments to pass down to the executable (man or apropos).

local manpages_picker = require("fuzzy.pickers.manpages")

manpages_picker.open_manpages_picker({
    args = { "-k", "." }
})

Vimdoc

Lists Neovim API docs from vim.fn.api_info(). Entries are structured with metadata (since, method/deprecated state, return type), can be filtered, and open the relevant help tag on confirm.

local vimdoc_picker = require("fuzzy.pickers.vimdoc")

vimdoc_picker.open_vimdoc_picker({
    preview = true,
    prefix = "nvim_",
    include_deprecated = true,
    include_private = false,
    sort_by = "name",
})

Options and behavior:

• prefix: Prefix filter for API names. Set false to disable.
• include_deprecated: Include deprecated APIs.
• deprecated_only: Show only deprecated APIs.
• include_private: Include private/internal API names (such as nvim__*).
• sort_by: "name" (default) or "since".
• preview: When enabled, shows signature/parameters/metadata for the selected API entry.

Tags

Tags pickers rely on ctags like output and are meant for code navigation. They keep content small to avoid storing huge tag lines in memory.

Tags

Lists tags in the project. Each entry shows the tag name and kind, and the picker opens the corresponding location on confirm.

local tags_picker = require("fuzzy.pickers.tags")

tags_picker.open_tags_picker({
})

Buffer Tags

Lists tags for the current buffer. This is the smallest tag picker and is useful when you want fast symbol navigation within a single file.

local btags_picker = require("fuzzy.pickers.btags")

btags_picker.open_btags_picker({
})

Registry

The picker registry stores and reuses picker instances. This is a small helper module that lets you register a picker under a key, retrieve it later, and open it without recreating a new instance. It is intentionally minimal and keeps the caching policy explicit in user code.

local registry = require("fuzzy.pickers.registry")

local picker = registry.register_picker_instance("buffers", my_buffers_picker)
local same_picker = registry.get_picker_instance("buffers")
registry.open_picker_instance("buffers")
registry.remove_picker_instance("buffers")
registry.clear_picker_registry()