vim-fzy

Quickly navigate to files under a directory, jump to lines matching a pattern using grep, open buffers, tags generated by ctags, Vim's help tags, old files, and file marks using the fuzzy-searcher fzy.

The terminal buffer can be displayed either in a normal window at the bottom of the screen or in a popup window.

Requirements

• fzy
• cut(1) (for the :FzyHelp command)
• find(1) or similar (for the :FzyFind command)
• grep(1) or similar (for the :FzyGrep command)

Commands

Command	Description
:FzyFind [dir]	Find files in [dir], edit selected file in the current window.
:FzyGrep {args}	Grep lines using pattern {args}, jump to selected location in the current window.
:FzyBuffer	List buffers, edit selected buffer in the current window.
:FzyArgs	List global arglist, edit selected file in the current window.
:FzyLargs	List local arglist, edit selected file in the current window.
:FzyOldfiles	List most recently used files, edit selected file in current window.
:FzyTjump	List tags, jump to selected tag in the current window.
:FzyMarks	List marks, jump to the selected mark in the current window.
:FzyHelp	List help tags, open help page with the selected tag in a new split.

[dir] is the directory to search in. If omitted, the search is performed in the current working directory. Environment variables can be passed, for example, :FzyFind $VIMRUNTIME.

Each command has a related command that opens the selected item in a new split, like :FzyBufferSplit. These commands accept a command modifier. For example, to open a buffer in a new vertical split, run :vert FzyBufferSplit, :tab FzyBufferSplit will open the selected buffer in a new tab. For a full list of supported command modifiers, see :help fzy-commands-split.

Configuration

Options can be passed to fzy through the dictionary g:fzy. The following entries are supported:

Entry	Description	Default
lines	Specify how many lines of results to show. This sets fzy's --lines option.	10
prompt	Set the fzy input prompt.	'▶ '
showinfo	If true, fzy is invoked with the --show-info option.	v:false
term_highlight	Highlight group for the terminal window.	'Terminal'
popupwin	Display fzy in a popup terminal.	v:false
popup	Popup window options (dictionary).	see below
findcmd	File-search command (string).	see below
grepcmd	Grep-search command.	&grepprg
grepformat	Format string for parsing the selected grep-output line.	&grepformat
histadd	If true, add edit command to history.	v:false

When popupwin is set to v:false, the terminal window is opened at the bottom of the screen and will occupy the full width of the Vim window.

Popup window options

The appearance of the popup window can be configured through the popup key. The following options can be set:

Entry	Description	Default
highlight	Highlight group for popup window padding and border.	'Pmenu'
padding	List with numbers defining padding between popup window and its border.	[0, 1, 0, 1]
border	List with numbers (0 or 1) specifying whether to draw a popup window border.	[1, 1, 1, 1]
borderchars	List with characters used for drawing the border.	['═', '║', '═', '║', '╔', '╗', '╝', '╚']
borderhighlight	List with highlight group names for drawing the border.¹	['Pmenu']
minwidth	Minimum width of popup window.	80

¹When only one item is specified it is used on all four sides.

Find command

If findcmd is not specified, the following default command is used:

find
  -name '.*'
  -a '!' -name .
  -a '!' -name .gitignore
  -a '!' -name .vim
  -a -prune
  -o '(' -type f -o -type l ')'
  -a -print 2> /dev/null
| cut -b3-

Broken down the expression means:

• Ignore all hidden files and directories, except for .gitignore, and .vim,
• print only files and symlinks.
• The cut command will remove the leading ./ from all file paths.

Example

g:fzy = {
    findcmd: 'fd --type f',
    grepcmd: 'grep -Hn',
    grepformat: '%f:%l:%m',
    histadd: true,
    prompt: '>>> ',
    showinfo: true,
    lines: 15,
    term_highlight: 'Pmenu',
    popupwin: true,
    popup: {
        borderchars: [' ']
    }
}

More examples can be found under :help fzy-config-examples.

Writing custom fzy commands

Writing custom commands that invoke fzy is very simple. Internally, the above commands call the Start() function that passes the items to fzy in a terminal window. The function is documented in :help fzy-api. Examples can be found in :help fzy-api-examples.

Installation

Run the following commands in your terminal:

$ cd ~/.vim/pack/git-plugins/start
$ git clone https://github.com/bfrg/vim-fzy
$ vim -u NONE -c 'helptags vim-fzy/doc | quit'

Note: The directory name git-plugins is arbitrary, you can pick any other name. For more details see :help packages. Alternatively, use your favorite plugin manager.

License

Distributed under the same terms as Vim itself. See :help license.