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.