*fff.nvim.txt*
                              For Neovim >= 0.10.0    Last change: 2026 May 20

==============================================================================
Table of Contents                                 *fff.nvim-table-of-contents*

1. fff.nvim                                                |fff.nvim-fff.nvim|

==============================================================================
1. fff.nvim                                                *fff.nvim-fff.nvim*

The best file search picker for Neovim. Frecency-ranked, typo-resistant,
git-award, very fast.

Demo on the Linux kernel repo (100k files, 8GB):


https://github.com/user-attachments/assets/5d0e1ce9-642c-4c44-aa88-01b05bb86abb


INSTALLATION ~


LAZY.NVIM

>lua
    {
      'dmtrKovalenko/fff.nvim',
      build = function()
        -- downloads a prebuilt binary or falls back to cargo build
        require("fff.download").download_or_build_binary()
      end,
      -- for nixos:
      -- build = "nix run .#release",
      opts = {
        debug = {
          enabled = true,
          show_scores = true,
        },
      },
      lazy = false, -- the plugin lazy-initialises itself
      keys = {
        { "ff", function() require('fff').find_files() end, desc = 'FFFind files' },
        { "fg", function() require('fff').live_grep() end, desc = 'LiFFFe grep' },
        { "fz",
          function() require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } }) end,
          desc = 'Live fffuzy grep',
        },
        { "fc",
          function() require('fff').live_grep({ query = vim.fn.expand("<cword>") }) end,
          desc = 'Search current word',
        },
      },
    }
<


VIM.PACK

>lua
    vim.pack.add({ 'https://github.com/dmtrKovalenko/fff.nvim' })
    
    vim.api.nvim_create_autocmd('PackChanged', {
      callback = function(ev)
        local name, kind = ev.data.spec.name, ev.data.kind
        if name == 'fff.nvim' and (kind == 'install' or kind == 'update') then
          if not ev.data.active then vim.cmd.packadd('fff.nvim') end
          require('fff.download').download_or_build_binary()
        end
      end,
    })
    
    vim.g.fff = {
      lazy_sync = true,
      debug = { enabled = true, show_scores = true },
    }
    
    vim.keymap.set('n', 'ff', function() require('fff').find_files() end, { desc = 'FFFind files' })
<


PUBLIC API ~

>lua
    require('fff').find_files()                        -- find files in current repo
    require('fff').live_grep()                         -- live content grep
    require('fff').scan_files()                        -- force rescan
    require('fff').refresh_git_status()                -- refresh git status
    require('fff').find_files_in_dir(path)             -- find in a specific dir
    require('fff').change_indexing_directory(new_path) -- change root
<


COMMANDS ~

- `:FFFScan`. Rescan files.
- `:FFFRefreshGit`. Refresh git status.
- `:FFFClearCache [all|frecency|files]`. Clear caches.
- `:FFFHealth`. Health check.
- `:FFFDebug [on|off|toggle]`. Toggle the scoring display.
- `:FFFOpenLog`. Open `~/.local/state/nvim/log/fff.log`.


CONFIGURATION ~

Defaults are sensible. Override only what you care about.

>lua
    require('fff').setup({
      base_path = vim.fn.getcwd(),
      prompt = '> ',
      title = 'FFFiles',
      max_results = 100,
      max_threads = 4,
      lazy_sync = true,
      prompt_vim_mode = false,
      layout = {
        height = 0.8,
        width = 0.8,
        prompt_position = 'bottom',   -- or 'top'
        preview_position = 'right',   -- 'left' | 'right' | 'top' | 'bottom'
        preview_size = 0.5,
        flex = { size = 130, wrap = 'top' },
        show_scrollbar = true,
        path_shorten_strategy = 'middle_number', -- 'middle_number' | 'middle' | 'end' | 'start'
        anchor = 'center',
      },
      preview = {
        enabled = true,
        max_size = 10 * 1024 * 1024,
        chunk_size = 8192,
        binary_file_threshold = 1024,
        imagemagick_info_format_str = '%m: %wx%h, %[colorspace], %q-bit',
        line_numbers = false,
        cursorlineopt = 'both',
        wrap_lines = false,
        filetypes = {
          svg = { wrap_lines = true },
          markdown = { wrap_lines = true },
          text = { wrap_lines = true },
        },
      },
      keymaps = {
        close = '<Esc>',
        select = '<CR>',
        select_split = '<C-s>',
        select_vsplit = '<C-v>',
        select_tab = '<C-t>',
        move_up = { '<Up>', '<C-p>' },
        move_down = { '<Down>', '<C-n>' },
        preview_scroll_up = '<C-u>',
        preview_scroll_down = '<C-d>',
        toggle_debug = '<F2>',
        cycle_grep_modes = '<S-Tab>',
        cycle_previous_query = '<C-Up>',
        toggle_select = '<Tab>',
        send_to_quickfix = '<C-q>',
        focus_list = '<leader>l',
        focus_preview = '<leader>p',
      },
      frecency = {
        enabled = true,
        db_path = vim.fn.stdpath('cache') .. '/fff_nvim',
      },
      history = {
        enabled = true,
        db_path = vim.fn.stdpath('data') .. '/fff_queries',
        min_combo_count = 3,
        combo_boost_score_multiplier = 100,
      },
      git = {
        status_text_color = false, -- true to color filenames by git status
      },
      grep = {
        max_file_size = 10 * 1024 * 1024,
        max_matches_per_file = 100,
        smart_case = true,
        time_budget_ms = 150,
        modes = { 'plain', 'regex', 'fuzzy' },
        trim_whitespace = false,
      },
      debug = { enabled = false, show_scores = false },
      logging = {
        enabled = true,
        log_file = vim.fn.stdpath('log') .. '/fff.log',
        log_level = 'info',
      },
    })
<


LIVE GREP MODES ~

`<S-Tab>` cycles between `plain`, `regex`, and `fuzzy`. The list is
configurable via `grep.modes`, and single-mode setups hide the indicator
entirely.

Per-call override:

>lua
    require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } })
    require('fff').live_grep({ query = 'search term' }) -- pre-fill
<


CONSTRAINTS ~

Both find and grep accept these tokens to refine a query:

- `git:modified`. One of `modified`, `staged`, `deleted`, `renamed`, `untracked`, `ignored`.
- `test/`. Any deeply nested children of `test/`.
- `!something`, `!test/`, `!git:modified`. Exclusion.
- `./**/*.{rs,lua}`. Any valid glob, powered by zlob <https://github.com/dmtrKovalenko/zlob>.

Grep-only:

- `*.md`, `*.{c,h}`. Extension filter.
- `src/main.rs`. Grep inside a single file.

Mix freely: `git:modified src/**/*.rs !src/**/mod.rs user controller`.


MULTI-SELECT AND QUICKFIX ~

- `<Tab>`. Toggle selection (shows a thick `▊` in the signcolumn).
- `<C-q>`. Send selected files to the quickfix list and close the picker.


GIT STATUS HIGHLIGHTING ~

Sign-column indicators are on by default. To color filename text by git status,
set `git.status_text_color = true` and adjust the `hl.git_*` groups. See `:help
fff.nvim` for the full list.


FILE FILTERING ~

FFF honours `.gitignore`. For picker-only ignores that do not touch git, add a
sibling `.ignore` file:

>gitignore
    *.md
    docs/archive/**/*.md
<

Run `:FFFScan` to force a rescan.


TROUBLESHOOTING ~

- `:FFFHealth` verifies picker init, optional dependencies, and DB connectivity.
- `:FFFOpenLog` opens the log file.

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
