fzf-lua Neovim Plugin

Use require("fzf-lua").setup() to configure global settings and specific picker options. You can pass tables for various configuration sections like winopts, keymap, actions, fzf_opts, fzf_colors, hls, and previewers. Many options can also be passed as functions that return an options table.

Common global options include:

• fzf_bin: Specify a custom fzf binary (e.g., 'sk' for skim).
• file_icon_padding: Add padding for terminal icon rendering.
• help_open_win: Override the function used to open the help window (defaults to vim.api.nvim_open_win).

require("fzf-lua").setup {
  winopts = { ... },     -- UI Options
  keymap = { ... },      -- Neovim keymaps / fzf binds
  actions = { ... },     -- Fzf "accept" binds
  fzf_opts = { ... },    -- Fzf CLI flags
  fzf_colors = { ... },  -- Fzf `--color` specification
  hls = { ... },         -- Highlights
  previewers = { ... },  -- Previewers options
  -- SPECIFIC COMMAND/PICKER OPTIONS
  files = { ... },
}

Customize the tabs() picker using the tabs configuration table. Key options include:

• prompt: The prompt string displayed.
• tab_title: The title for each tab.
• tab_marker: The marker used to identify the current tab.
• locate: If true, positions the cursor at the current window.
• file_icons / color_icons: Control icon display and coloring.
• actions: Define custom keybindings. For example, mapping enter to actions.buf_switch or ctrl-x to actions.buf_del with reload = true to prevent window flashing.

tabs = {
  prompt            = 'Tabs❯ ',
  tab_title         = "Tab",
  tab_marker        = "<<",
  locate            = true,
  file_icons        = true,
  color_icons       = true,
  actions = {
    ["enter"]       = actions.buf_switch,
    ["ctrl-x"]      = { fn = actions.buf_del, reload = true },
  },
  fzf_opts = {
    ["--delimiter"] = "[\\):]",
    ["--with-nth"]  = '2..',
  },
}

The fzf_colors table controls the terminal colorscheme for fzf.

Options:

• true: Automatically generate a colorscheme from Neovim's current colorscheme.
• Custom Table: Define specific colors for fzf elements.

Custom Color Syntax:

• If the value is a string, it is passed raw (e.g., ["fg"] = "underline" becomes --color fg:underline).
• If the value is a table, it follows this convention: [1] is the attribute (e.g., "fg", "bg"), [2] is the Neovim highlight group(s) (string or table), and [3+] are additional raw arguments.

Example of a fully loaded color option: ["fg"] = { "fg", { "NonExistentHl", "Comment" }, "underline", "bold" } results in --color fg:#010101:underline:bold (assuming Comment.fg is #010101).

fzf_colors = {
      true,   -- inherit fzf colors that aren't specified below
      ["fg"]          = { "fg", "CursorLine" },
      ["bg"]          = { "bg", "Normal" },
      ["hl"]          = { "fg", "Comment" },
      ["fg+"]         = { "fg", "Normal", "underline" },
      ["bg+"]         = { "bg", { "CursorLine", "Normal" } },
      ["hl+"]         = { "fg", "Statement" },
      ["info"]        = { "fg", "PreProc" },
      ["prompt"]      = { "fg", "Conditional" },
      ["pointer"]     = { "fg", "Exception" },
      ["marker"]      = { "fg", "Keyword" },
      ["spinner"]     = { "fg", "Label" },
      ["header"]      = { "fg", "Comment" },
      ["gutter"]      = "-1",
  }

The git configuration provides specialized pickers for Git-related tasks. It is divided into several sub-pickers:

• files: Search for files tracked by Git.
• status: View and interact with the Git status (stage/unstage/reset).
• diff: View changes between commits.
• hunks: View individual hunks in a diff.
• commits: Browse and checkout commits.
• bcommits: Browse buffer history across renames.
• blame: View git blame information.
• branches: List and switch between branches.
• tags: List and checkout tags.
• stash: Manage Git stashes.

You can customize commands (cmd), previews (preview), and keybindings (actions) for each sub-picker.

git = {
  files = {
    prompt        = 'GitFiles❯ ',
    cmd           = 'git ls-files --exclude-standard',
  },
  status = {
    prompt        = 'GitStatus❯ ',
    cmd           = "git -c color.status=false --no-optional-locks status --porcelain=v1 -u",
    actions = {
      ["right"]  = { fn = actions.git_unstage, reload = true },
      ["left"]   = { fn = actions.git_stage, reload = true },
      ["ctrl-x"] = { fn = actions.git_reset, reload = true },
    },
  },
  branches = {
    prompt   = 'Branches❯ ',
    cmd      = "git branch --all --color",
    actions  = {
      ["enter"]   = actions.git_switch,
      ["ctrl-x"]  = { fn = actions.git_branch_del, reload = true },
      ["ctrl-a"]  = { fn = actions.git_branch_add, field_index = "{q}", reload = true },
    },
  },
}