< div align = "center" >
# fzf :heart: lua
![Neovim version ](https://img.shields.io/badge/Neovim-0.5-57A143?style=flat-square&logo=neovim )
[Installation ](#installation ) • [Usage ](#usage ) • [Commands ](#commands ) • [Customization ](#customization ) • [Wiki ](https://github.com/ibhagwan/fzf-lua/wiki )
![screenshot ](https://raw.githubusercontent.com/ibhagwan/fzf-lua/main/screenshots/main.png )
[fzf ](https://github.com/junegunn/fzf ) changed my life, it can change yours too, if you allow it.
< / div >
### Rationale
What more can be said about [fzf ](https://github.com/junegunn/fzf )? It is the
single most impactful tool for my command line workflow, once I started using
fzf I couldn’ t see myself living without it.
> **To understand fzf properly I highly recommended [fzf
> screencast](https://www.youtube.com/watch?v=qgG5Jhi_Els) by
> [@samoshkin](https://github.com/samoshkin)**
This is my take on the original
[fzf.vim ](https://github.com/junegunn/fzf.vim ), written in lua for neovim 0.5,
it builds on the elegant
[nvim-fzf ](https://github.com/vijaymarupudi/nvim-fzf ) as an async interface to
create a performant and lightweight fzf client for neovim that rivals any of
the new shiny fuzzy finders for neovim.
### Why use this plug-in?
... and not, to name a few,
[telescope ](https://github.com/nvim-telescope/telescope.nvim ) or
[vim-clap ](https://github.com/liuchengxu/vim-clap )?
As [@junegunn ](https://github.com/junegunn ) himself put it, “because you can
and you love `fzf` ”.
If you’ re happy with your current setup there is absolutely no reason to switch.
That said, without taking anything away from the greatness of other plugins I
found it more efficient having a uniform experience between my shell and my
nvim. In addition `fzf` has been a rock for me since I started using it and
hadn’ t failed me once, it never hangs and can handle almost anything you throw
at it. That, **and colorful file icons and git indicators!** .
### Dependencies
- `Linux` or `MacOS` only, see [nvim-fzf's How it
works](https://github.com/vijaymarupudi/nvim-fzf#How-it-works) section
- [`fzf` ](https://github.com/junegunn/fzf ) binary installed
- [nvim-fzf ](https://github.com/vijaymarupudi/nvim-fzf )
- [nvim-web-devicons ](https://github.com/kyazdani42/nvim-web-devicons )
(optional)
### Optional dependencies (recommended)
- [fd ](https://github.com/sharkdp/fd ) - better performance `find` utility
- [bat ](https://github.com/sharkdp/bat ) - for colorful syntax highlighted previews
- [ripgrep ](https://github.com/BurntSushi/ripgrep ) - for better grep-like searches
### Installation
Using [vim-plug ](https://github.com/junegunn/vim-plug )
```vim
Plug 'ibhagwan/fzf-lua'
Plug 'vijaymarupudi/nvim-fzf'
Plug 'kyazdani42/nvim-web-devicons'
```
Using [packer.nvim ](https://github.com/wbthomason/packer.nvim )
```lua
use { 'ibhagwan/fzf-lua',
requires = {
'vijaymarupudi/nvim-fzf',
'kyazdani42/nvim-web-devicons' } -- optional for icons
}
```
> **Note** if you already have fzf installed you do not need to install `fzf`
> or `fzf.vim`, however if you do not have it installed, **you only need** fzf
> which can be installed with (fzf.vim is not a requirement nor conflict):
> ```vim
> Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
> ```
> or with [packer.nvim](https://github.com/wbthomason/packer.nvim):
>```lua
>use = { 'junegunn/fzf', run = './install --bin', }
>```
## Usage
Fzf-lua aims to be as plug and play as possible with sane defaults, you can
run any fzf-lua command like this:
```lua
:lua require('fzf-lua').files()
```
or with arguments:
```lua
:lua require('fzf-lua').files({ cwd = '~/.config' })
```
which can be easily mapped to:
```vim
nnoremap < c-P > < cmd > lua require('fzf-lua').files()< CR >
```
## Commands
| Command | List |
| --- | --- |
|`buffers`|open buffers|
|`files`|`find` or `fd` on a path|
|`git_files`|`git ls-files`|
|`oldfiles`|opened files history|
|`quickfix`|quickfix list|
|`loclist`|location list|
|`grep`|search for a pattern with `grep` or `rg` |
|`grep_last`|run search again with the last pattern|
|`grep_cword`|search word under cursor|
|`grep_cWORD`|search WORD under cursor|
|`grep_visual`|search visual selection|
|`grep_curbuf`|live grep current buffer|
|`live_grep`|live grep current project|
|`help_tags`|help tags|
|`man_pages`|man pages|
|`colorschemes`|color schemes|
|`builtin`|fzf-lua builtin methods|
## LSP Commands
| Command | List |
| --- | --- |
|`lsp_references`|References|
|`lsp_definitions`|Definitions|
|`lsp_declarations`|Declarations|
|`lsp_typedefs`|Type Definitions|
|`lsp_implementations`|Implementations|
|`lsp_document_symbols`|Document Symbols|
|`lsp_workspace_symbols`|Workspace Symbols|
|`lsp_code_actions`|Code Actions|
|`lsp_document_diagnostics`|Document Diagnostics|
|`lsp_workspace_diagnostics`|Workspace Diagnostics|
## Customization
I tried to make it as customizable as possible, if you find you need to change something that isn’ t below, open an issue and I’ ll do my best to add it.
customization can be achieved by calling the `setup()` function or individually sending parameters to a builtin command, for exmaple:
```lua
:lua require('fzf-lua').files({ fzf_layout = 'reverse-list' })
```
Consult the list below for available settings:
```lua
local actions = require "fzf-lua.actions"
require'fzf-lua'.setup {
win_height = 0.85, -- window height
win_width = 0.80, -- window width
win_row = 0.30, -- window row position (0=top, 1=bottom)
win_col = 0.50, -- window col position (0=left, 1=right)
-- win_border = false, -- window border? or borderchars?
win_border = { '╭', '─', '╮', '│', '╯', '─', '╰', '│' },
-- fzf_bin = 'sk', -- use skim instead of fzf?
fzf_layout = 'reverse', -- fzf '--layout='
fzf_args = '', -- adv: fzf extra args, empty unless adv
preview_cmd = '', -- 'head -n $FZF_PREVIEW_LINES',
preview_border = 'border', -- border|noborder
preview_wrap = 'nowrap', -- wrap|nowrap
preview_opts = 'nohidden', -- hidden|nohidden
preview_vertical = 'down:45%', -- up|down:size
preview_horizontal = 'right:60%', -- right|left:size
preview_layout = 'flex', -- horizontal|vertical|flex
flip_columns = 120, -- #cols to switch to horizontal on flex
bat_theme = 'Coldark-Dark', -- bat preview theme (bat --list-themes)
bat_opts = '--style=numbers,changes --color always',
files = {
prompt = 'Files❯ ',
cmd = '', -- "find . -type f -printf '%P\n'",
git_icons = true, -- show git icons?
file_icons = true, -- show file icons?
color_icons = true, -- colorize file|git icons
actions = {
["default"] = actions.file_edit,
["ctrl-s"] = actions.file_split,
["ctrl-v"] = actions.file_vsplit,
["ctrl-t"] = actions.file_tabedit,
["ctrl-q"] = actions.file_sel_to_qf,
["ctrl-y"] = function(selected) print(selected[2]) end,
}
},
git = {
prompt = 'GitFiles❯ ',
cmd = 'git ls-files --exclude-standard',
git_icons = true, -- show git icons?
file_icons = true, -- show file icons?
color_icons = true, -- colorize file|git icons
icons = {
["M"] = { icon = "M", color = "yellow" },
["D"] = { icon = "D", color = "red" },
["A"] = { icon = "A", color = "green" },
["?"] = { icon = "?", color = "magenta" },
-- ["M"] = { icon = "★", color = "red" },
-- ["D"] = { icon = "✗", color = "red" },
-- ["A"] = { icon = "+", color = "green" },
},
},
grep = {
prompt = 'Rg❯ ',
input_prompt = 'Grep For❯ ',
-- cmd = "rg --vimgrep",
rg_opts = "--hidden --column --line-number --no-heading --color=always --smart-case -g '!{.git,node_modules}/*'",
git_icons = true, -- show git icons?
file_icons = true, -- show file icons?
color_icons = true, -- colorize file|git icons
actions = {
["default"] = actions.file_edit,
["ctrl-s"] = actions.file_split,
["ctrl-v"] = actions.file_vsplit,
["ctrl-t"] = actions.file_tabedit,
["ctrl-q"] = actions.file_sel_to_qf,
["ctrl-y"] = function(selected) print(selected[2]) end,
}
},
oldfiles = {
prompt = 'History❯ ',
cwd_only = false,
},
buffers = {
prompt = 'Buffers❯ ',
file_icons = true, -- show file icons?
color_icons = true, -- colorize file|git icons
sort_lastused = true, -- sort buffers() by last used
actions = {
["default"] = actions.buf_edit,
["ctrl-s"] = actions.buf_split,
["ctrl-v"] = actions.buf_vsplit,
["ctrl-t"] = actions.buf_tabedit,
["ctrl-x"] = actions.buf_del,
}
},
colorschemes = {
prompt = 'Colorschemes❯ ',
live_preview = true,
actions = {
["default"] = actions.colorscheme,
["ctrl-y"] = function(selected) print(selected[2]) end,
},
winopts = {
win_height = 0.55,
win_width = 0.30,
window_on_create = function()
vim.cmd("set winhl=Normal:Normal")
end,
},
post_reset_cb = function()
require('feline').reset_highlights()
end,
},
quickfix = {
-- cwd = vim.loop.cwd(),
file_icons = true,
git_icons = true,
},
lsp = {
prompt = '❯ ',
-- cwd = vim.loop.cwd(),
file_icons = true,
git_icons = false,
lsp_icons = true,
severity = "hint",
icons = {
["Error"] = { icon = "", color = "red" }, -- error
["Warning"] = { icon = "", color = "yellow" }, -- warning
["Information"] = { icon = "", color = "blue" }, -- info
["Hint"] = { icon = "", color = "magenta" }, -- hint
},
},
-- placeholders for additional user customizations
loclist = {},
helptags = {},
manpages = {},
file_icon_colors = { -- override colors for extensions
["lua"] = "blue",
},
fzf_binds = { -- fzf '--bind=' options
'f2:toggle-preview',
'f3:toggle-preview-wrap',
'shift-down:preview-page-down',
'shift-up:preview-page-up',
'ctrl-d:half-page-down',
'ctrl-u:half-page-up',
'ctrl-f:page-down',
'ctrl-b:page-up',
'ctrl-a:toggle-all',
'ctrl-l:clear-query',
},
window_on_create = function() -- nvim window options override
vim.cmd("set winhl=Normal:Normal") -- popup bg match normal windows
end,
}
```
This can also be run from a `.vim` file using
```lua
lua < < EOF
require('fzf-lua').setup{
-- ...
}
EOF
```
### Known issues
- [ ] `live_grep` has icons disabled until I find a solution for fzf's
`change:reload` event
- [ ] Tested mostly with both `rg` , `fd` and `bat` installed, there might be
issues with the default `grep` , `find` and `head` alternatives
## TODO
- Add more providers
+ [x] ~~LSP (refs, symbols, etc)~~ (2021-07-20)
+ [ ] git commits
+ [ ] git branches
+ [ ] vim commands
+ [ ] vim command history
+ [ ] vim keymaps
+ [ ] vim options
+ [ ] search history
+ [ ] tags
+ [ ] marks
+ [ ] registers
+ [ ] spelling suggestions
- [ ] Add built-in plugin documentation
- [ ] Add "hidden" options documentation
- [ ] Add FAQ
### Credits
Big thank you to all those I borrowed code/ideas from, I read so many configs
and plugin codes that I probably forgot where I found some samples from so if
I missed your name feel free to contact me and I'll add it below:
- [@vijaymarupudi ](https://github.com/vijaymarupudi/ ) for his wonderful
[nvim-fzf ](https://github.com/vijaymarupudi/nvim-fzf ) plugin which is in the
core of this plugin
- [@tjdevries ](https://github.com/tjdevries/ ) for too many great things to
list here and for borrowing some of his
[nvim-telescope ](https://github.com/nvim-telescope/telescope.nvim ) provider
code
- [@lukas-reineke ](https://github.com/lukas-reineke ) for inspiring the
solution after browsing his
[dotfiles ](https://github.com/lukas-reineke/dotfiles ) and coming across his
[fuzzy.lua ](https://github.com/lukas-reineke/dotfiles/blob/master/vim/lua/fuzzy.lua )
, and while we're, also here for his great lua plugin
[indent-blankline ](https://github.com/lukas-reineke/indent-blankline.nvim )
- [@sindrets ](https://github.com/sindrets ) for borrowing utilities from his
fantastic lua plugin [diffview.nvim ](https://github.com/sindrets/diffview.nvim )