native telescope bindings to zf for sorting results.
In short, zf is a filepath fuzzy finder. It is designed for better matching on filepaths than fzf or fzy. Matches on filenames are prioritized, and the strict path matching feature helps narrow down directory trees with precision. See the zf repo for full details. Some highlights:
- a match on the filename is prioritized over a match on the full path
- a search including path separators enables "strict path matching"
- this means each path segment in the query must be found in a path segment of the file
src/would matchsrc/index.jsbut nottests/routes/client/index.js
- the search query is space-separated to make narrowing down results easier
- searching for
init.pywould find several__init__.pyfiles in a Python project - but a search for
init.py cwould match./config/__init__.py(or any other paths also containingc)
- searching for
By default, telescope uses a sorter implemented in Lua. This is fine, but performance can suffer on larger lists of data.
telescope-zf-native.nvim is a telescope extension that provides a more performant natively-compiled sorter written in Zig with more accurate filename matching using the zf algorithm. Pre-compiled libzf binaries are included. See below for the current list of supported platforms and architectures.
See the zf repo for more information on
the algorithm and standalone executable (a replacement for fzf or fzy). But
here's a short summary:
After analyzing filenames from over 50 git repositories selected randomly from GitHub, I concluded that the majority of filenames are unique in a project. I used this in designing the zf algorithm to make a fuzzy-finder that is optimized for filtering filepaths.
- Matches on filenames are highly favored over filepath matches
- Matches on the beginning of a word are prioritized over matches in the middle of a word
- Non-sequential character matches are penalized
With these heuristics, zf does a really good job sorting the desired file to the
top of the results list. But there are plenty of files that share the same or
similar names like init.lua or __init__.py for example. zf parses the query
string as a list of space-delimited tokens to easily refine the search results
when the first match isn't the wanted file. Simply append further terms to the
query to narrow down the results.
Install in neovim with a package manager like packer.nvim or vim-plug.
--- packer
use "natecraddock/telescope-zf-native.nvim"If you are using lazy.nvim and experience troubles installing the plugin, try something like the following (see this issue for more details):
require('lazy').setup('my_plugins', { rocks = { enabled = false } })Then load the extension in telescope with default settings.
require("telescope").load_extension("zf-native")The default config replaces the default telescope sorters with zf for all
sorting. To confirm that the extension loaded properly, and to view the current
settings, run :checkhealth zf-native.
For additional configuration, use the following:
require("telescope").setup({
extensions = {
["zf-native"] = {
-- options for sorting file-like items
file = {
-- override default telescope file sorter
enable = true,
-- highlight matching text in results
highlight_results = true,
-- enable zf filename match priority
match_filename = true,
-- optional function to define a sort order when the query is empty
initial_sort = nil,
-- set to false to enable case sensitive matching
smart_case = true,
},
-- options for sorting all other items
generic = {
-- override default telescope generic item sorter
enable = true,
-- highlight matching text in results
highlight_results = true,
-- disable zf filename match priority
match_filename = false,
-- optional function to define a sort order when the query is empty
initial_sort = nil,
-- set to false to enable case sensitive matching
smart_case = true,
},
}
},
})
require("telescope").load_extension("zf-native")The above settings are the default, so if you are satisfied with the defaults there is no need to change anything.
The initial_sort function is used when the query is empty.
Here is an example that prioritizes .lua files
['zf-native'] = {
file = {
initial_sort = function (line)
if line:match('.lua$') then
return 0
end
return 1
end
}
}The function accepts a line to rank and should return a number between 0 and 1, with numbers closer to 0 giving the line a higher priority.
The lib/ directory contains libzf pre-compiled libraries for:
- linux (x86 and arm)
- macos (x86 and arm)
- windows (x86)
If your OS is not supported, or there are issues loading the libraries please
submit an issue. For requests of support of new platforms or any other issue,
please include the output of :checkhealth zf-native in the issue.
I also thank the developers who worked on these projects as my reference for using the LuaJIT FFI.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent