I am no longer maintaining this plugin. To my knowledge, it still functions perfectly fine as a simple fuzzy finder interface for neovim.
When I first wrote nvim-find, I wanted a better fuzzy-finder matching experience in neovim, because I'm not perfectly happy with fzf or fzy's algorithms. So I made this plugin.
Later, after telescope.nvim fixed a few missing features, I realized it would be a better use of my time to use telescope for my fuzzy finder interface, and make my own algorithm to be used in telescope and in the terminal.
So I have created zf as a replacement to fzf and fzy, and telescope-zf-native.nvim to integrate zf with telescope. This means I don't have to maintain a fuzzy finding interface and a sorting algorithm.
So you are welcome to use this, but I would recommend using telescope and zf if you want to have a filename matching algorithm similar to nvim-find.
A fast and simple finder plugin for Neovim
- Speed: The finder should open fast and filter quickly
- Simplicity: The finder should be unobtrusive and not distract from flow
- Extensible: It should be easy to create custom finders
For usage instructions see the Finders section below.
- Files: Find files in the current working directory respecting gitignore
- Buffers: List open buffers
- Search: Search using ripgrep in the current working directory
Requires Neovim >= v0.5.0
Optional dependencies:
fdfor listing files.ripgrepfor listing files or for project search.ripgrepmay be used in place of fd for listing files.
Install with a plugin manager such as:
use 'natecraddock/nvim-find'
Plug 'natecraddock/nvim-find'
Access the config table by requiring nvim-find.config. Edit the values of the config table
to change how nvim-find behaves. For example:
local cfg = require("nvim-find.config")
cfg.height = 14 -- set max heightThe available options are as follows, with their default values:
local cfg = require("nvim-find.config")
-- maximum height of the finder
cfg.height = 20
-- maximum width of the finder
cfg.width = 100
-- list of ignore globs for the filename filter
-- e.g. "*.png" will ignore any file ending in .png and
-- "*node_modules*" ignores any path containing node_modules
cgf.files.ignore = {}
-- start with all result groups collapsed
cfg.search.start_closed = falseFinders are not mapped by default. Each section below indicates which function to map to enable quick access to the finder. The default command is also listed if available.
If a finder is transient then it can be closed immediately with esc. A non-transient finder will return to normal mode when esc is pressed.
Finders open centered at the top of the terminal window. Any finder with a file preview draws centered and is expanded to fill more of the available space.
These mappings are always enabled when a finder is open
| Key(s) | Mapping |
|---|---|
| ctrl-j or ctrl-n | select next result |
| ctrl-k or ctrl-p | select previous result |
| ctrl-c | close finder |
| esc or ctrl-[ | close finder if transient or enter normal mode |
A non-transient finder has the following additional mappings in normal mode
| Key(s) | Mapping |
|---|---|
| j or n | select next result |
| k or p | select previous result |
| ctrl-c or esc or ctrl-[ | close finder |
Transient. Find files in the current working directory.
Because the majority of file names are unique within a project, the file finder does not do fuzzy-matching. The query is separated into space-delimited tokens. The first token is used to filter the file list by file name. The remaining tokens are used to further reduce the list of results by matching against the full file paths.
Additionally, if no matches are found, then the first token will be matched against the full path rather than only the filename.
Although this finder does not do fuzzy-matching, there is still some degree of sloppiness allowed. If the characters
-_. are not included in the query they will be ignored in the file paths. For example, the query
outlinerdrawc matches the file outliner_draw.c.
This algorithm is the main reason I created nvim-find.
Example mapping:
nnoremap <silent> <c-p> :lua require("nvim-find.defaults").files()<cr>
Command: :NvimFindFiles
| Key | Mapping |
|---|---|
| enter | open selected file in last used buffer |
| ctrl-v | split vertically and open selected file |
| ctrl-s | split horizontally and open selected file |
| ctrl-t | open selected file in a new tab |
Transient. List open buffers.
Lists open buffers. The alternate buffer is labeled with (alt), and any buffers with unsaved changes
are prefixed with a circle icon.
Example mapping:
nnoremap <silent> <leader>b :lua require("nvim-find.defaults").buffers()<cr>
Command: :NvimFindBuffers
| Key | Mapping |
|---|---|
| enter | open selected file in last used buffer |
| ctrl-v | split vertically and open selected file |
| ctrl-s | split horizontally and open selected file |
| ctrl-t | open selected file in a new tab |
Non-transient. Search files in the current working directory with ripgrep with a preview.
This finder shows a preview of the match in context of the file. The results are grouped by file, and tab can be used to expand or collapse a file's group. After choosing a result the lines are also sent to the quickfix list for later reference.
To search for the word under the cursor, an additional function is exposed
require("nvim-find.defaults").search_at_cursor().
In cases where more than a single word should be searched for, the desired text can be selected
in visual mode. Then calling require("nvim-find.defaults").search() will search for the selected
text. This requires a visual mode mapping.
Example mapping:
nnoremap <silent> <leader>f :lua require("nvim-find.defaults").search()<cr>
Command: :NvimFindSearch
| Key | Mapping |
|---|---|
| gg | scroll to the top of the list |
| G | scroll to the bottom of the list |
| tab | open or close current group fold |
| o | open or close all group folds (toggles) |
| ctrl-q (insert) or q (normal) | send results to the quickfix list and close |
| enter | insert: switch to normal mode. normal: open selected match in last used buffer |
| ctrl-v | split vertically and open selected match |
| ctrl-s | split horizontally and open selected match |
| ctrl-t | open selected match in a new tab |
If you find a bug, have an idea for a new feature, or even write some code you want included, please create an issue or pull request! I would appreciate contributions. Note that plan to keep nvim-find simple, focused, and opinionated, so not all features will be accepted.
This is my first vim/neovim plugin, and first project in Lua. I have relied on telescope.nvim, plenary.nvim, and Snap for help on how to interact with the neovim api, and for inspiration on various parts of this plugin. Thanks to all the developers for helping me get started!
The async design of nvim-find is most heavily inspired by Snap.