fzfx.nvim

A Neovim fuzzy finder that updates on every keystroke.

https://github.com/linrongbin16/fzfx.nvim/assets/6496887/b5e2b0dc-4dd6-4c18-b1da-f54419efbba3

Search require("fzfx with rg's -g *spec.lua -F option.

📖 Table of contents

• Features
• Requirements
  • Windows
• Install
• Usage
  • Files & Buffers
  • Grep
  • Git
  • Lsp & Diagnostics
  • Vim
  • Misc
• Recommended Key Mappings
• Configuration
  • Feature Flags
  • Create Your Own Command
  • API References
• Known Issues
• Alternatives
• Development
• Contribute

✨ Features

• Colors/icons, Windows and modern Neovim features support.
• Updates on every keystroke of user query and selection.
• Multiple variants to avoid manual input:
  • Search by visual select.
  • Search by cursor word.
  • Search by yank text.
  • Search by resume last search.
• Multiple data sources to avoid restart search flow:
  • Exclude or include hiddens/ignores when searching files.
  • Local or remote when searching git branches.
  • Whole workspace or current buffer only when searching diagnostics.
  • ...
• And a lot more.

Please see Demo for more use cases.

✅ Requirements

[!NOTE]

This plugin keeps up with the latest Neovim stable version, supports until the last legacy version, while earlier versions are dropped to reduce maintenance effort.

For example, at the time of writing (2024-06-11), stable is 0.10, last legacy is 0.9, nightly is 0.11, thus this plugin supports 0.9+.

• Neovim ≥ 0.9.
• fzf.
• curl (for query fzf status or update preview label).
• nerd-fonts (optional for icons).
• rg (optional for live grep, by default use grep).
• fd (optional for find files, by default use find).
• bat (optional for preview files, by default use cat).
• git (mandatory for all git commands).
• delta (optional for preview git diff, show, blame).
• lsd/eza (optional for file explorer, by default use ls).

Windows

Besides those rust-written commands mentioned above (rg/fd/bat), Windows users will have to install the linux shell environment and core utils, since basic shell commands such as echo, mkdir are internally required.

Click here to see how to install linux commands

There're many ways to install portable linux shell and core utils on Windows, personally I would recommend below two methods: #### [Git for Windows](https://git-scm.com/download/win) Install with the below 3 options: - In **Select Components**, select **Associate .sh files to be run with Bash**. - In **Adjusting your PATH environment**, select **Use Git and optional Unix tools from the Command Prompt**. - In **Configuring the terminal emulator to use with Git Bash**, select **Use Windows's default console window**. After this step, **git.exe** and builtin linux commands(such as **echo.exe**, **ls.exe**, **curl.exe**) will be available in `%PATH%`. #### [scoop](https://scoop.sh/) Run below powershell commands: ```powershell # scoop Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex scoop bucket add extras scoop install git # git, bash, sh scoop install mingw # echo, grep, find, curl, ls, cat scoop install coreutils # echo, grep, find, curl, ls, cat ``` #### Fix conflicts between embedded commands from `C:\Windows\System32` and linux commands Windows actually already provide some builtin commands (`find.exe`, `bash.exe`) in `C:\Windows\System32` (or `%SystemRoot%\system32`), but they are not the linux commands they are named after, while could override above installations. To fix it, we need to prioritize (move up) the git or scoop environment variables in `%PATH%`.

📦 Install

[!NOTE]

You can specify the plugin version/tag (i.e. v5.*) to avoid break changes between major versions!

🚀 Usage

There're multiple commands provided, named with prefix Fzfx. The sub commands indicates the user query's input method, (i.e. the variants) named with below conventions:

• Basic variant is named with args, accepts the following arguments as query content.
• Visual select variant is named with visual, uses visual selection as query content.
• Cursor word variant is named with cword, uses the word text under cursor as query content.
• Put (i.e. yank text) variant is named with put (just like press the p key), uses the yank text as query content.
• Resume last search variant is named with resume, uses the last search content as query content.

[!NOTE]

The args sub command can be omitted, for example :FzfxFiles<CR> is equivalent to :FzfxFiles args<CR>.

To specify query text, for example asdf, you will have to type :FzfxFiles args asdf<CR>.

Below keys are binded by default:

• Exit keys (fzf --expect option)
  • esc: quit.
  • double-click/enter: open/jump to file (behave different on some specific commands).
• Preview keys
  • alt-p: toggle preview.
  • ctrl-f: preview half page down.
  • ctrl-b: preview half page up.
• Select keys
  • ctrl-e: toggle select.
  • ctrl-a: toggle select all.

Files & Buffers

Grep

Git

Lsp & Diagnostics

Vim

Misc

📌 Recommended Key Mappings

🔧 Configuration

To configure options, please use:

require('fzfx').setup(opts)

The opts is an optional lua table that override the default options.

For complete default options, please see config.lua.

For advanced configurations, please check Advanced Configuration.

Feature Flags

To enable/disable some features, please define below global variables before setup this plugin:

• vim.g.fzfx_disable_buffer_previewer: Disable nvim buffer for previewing file contents, use fzf builtin preview window via bat with best performance.

  Click here to see how to configure

  ```vim " vim scripts let g:fzfx_disable_buffer_previewer = 1 " or v:true ``` ```lua -- lua scripts vim.g.fzfx_disable_buffer_previewer = 1 -- or true ```

Create Your Own Command

Here's a minimal example that implement the ls -1 like FzfxLs command:

https://github.com/linrongbin16/fzfx.nvim/assets/6496887/c704e5b2-d82a-45f2-8920-adeec5d3e7c2

First setup this plugin, then use require("fzfx").register(name, opts}) api to create your own searching command.

For detailed explanation of each components, please see A Generic Schema for Creating FZF Command and schema.lua.

API References

To help easier customizing/integrating, fzfx provides below modules and APIs.

It's highly recommended to use these APIs when you're creating a new searching command, rather than start from scratch, since they are usually robust and take various situations into consideration.

• fzfx.cfg: Top-level configurations that directly register the searching command, such as FzfxFiles, FzfxLiveGrep, etc. Each module is an independent configuration.
• fzfx.helper: Line-oriented utilities for parsing user input, query results and rendering the lines for (both left side and right side of) the fzf binary. Since a searching command is actually all about the lines: generating, previewing and invoking binded function on the lines.

• fzfx.lib: Fundamental infrastructures, fzfx uses the commons.nvim library as a common utility lua library, please also refer to the commons.nvim's documentation.

  The commons.nvim library was originally part of fzfx.lib, since I found they're so commonly used and I almost need them for every of my Neovim plugins, I extracted them into this library.

Please see API References for more details.

🪲 Known Issues

Please see Known Issues if you encountered any issue.

🍀 Alternatives

• fzf.vim: Things you can do with fzf and Vim.
• fzf-lua: Improved fzf.vim written in lua.
• telescope.nvim: Find, Filter, Preview, Pick. All lua, all the time.

✏️ Development

To develop the project and make PR, please setup with:

• lua_ls.
• stylua.
• selene.

To run unit tests, please install below dependencies:

• vusted.

Then test with vusted ./spec.

🎁 Contribute

Please open issue/PR for anything about fzfx.nvim.

Like fzfx.nvim? Consider