fzf is a fast and powerful fuzzy file search tool on the command-line. In this post, I will introduce its installation and usage.

Installation

Two step install

We can use git to install fzf:

git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

The above command will install fzf under ~/.fzf/bin.

If you want to enable fzf inside Neovim, add the following setting to Neovim configuration (suppose your plugin manager is vim-plug):

Plug '~/.fzf'

One step install

We can install fzf and enable it inside Neovim in one step. Use the following configuration for Neovim:

Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }

You can change the directory where you want to install fzf.

How to use

As Nvim plugin

Inside Nvim, we can search and open files quickly using the command provided by fzf:

:FZF " find file under current directory
:FZF ~ " find file under HOME directory

For convenience, we can add shortcut mappings for the above commands:

nnoremap <silent> <leader>f :FZF<cr>
nnoremap <silent> <leader>F :FZF ~<cr>

You can use Ctrl + N and Ctrl + P or the arrow key to navigate through the list of files found by fzf. To open the file in Neovim, fzf provides several shortcut key:

  • <Enter>: open file in current window
  • Ctrl + T: open file in new tab page
  • Ctrl + X: open file in new horizontal window
  • Ctrl + V: open file in new vertical window

To close the file search window, use Esc or Ctrl+C.

Use fzf with other command

You can also use fzf in conjunction with other command. For example, you can use fzf and nvim together. Fzf is used to find the file and then open the file with nvim:

nvim $(fzf)

Use fzf alone

Fzf provide several command-line shortcut after installation:

  • Ctrl + T: paste the path of file or directory found on the command line
  • Ctrl + R: find history command and paste command on the command line
  • Alt + C: cd to specific directory

Note that Ctrl + T 和 Alt + C will only find file or folder under current directory. If you can not find a file, please make sure that it exists under current directory.

By default, fzf use find to search files. You can use the variable FZF_DEFAULT_COMMAND to change the default search command. For example, if you have installed the silver searcher, AKA, ag, you may want to use the following setting in your .bash_profile:

export FZF_DEFAULT_COMMAND='ag --hidden --ignore .git -g ""'

Autocompletion on command line

Auto-complete file or directory names

When you are using vim and cd, you can activate file and directory fuzzy completion with ** as a trigger (press Tab to trigger auto-completion):

vim **<TAB> # open file under current directory
vim ../**<TAB> # open file under parent directory
vim ~/**<TAB> # open file under $HOME

cd **<TAB> # go to a directory under current directory

The auto-completion function only supports a few commands. If you want to add your own command, say, pylint, it is easy to set up. Following the guide here, you need to add the below command to your .bash_profile:

complete -o bashdefault -o default -F _fzf_path_completion pylint

Do not forget to source your .bash_profile. Then you can trigger auto-complete for pylint just like what you do with vim and cd:

# open some file under home directory in a recursive manner
pylint ~/**<TAB>

Autocompletion for environment variables

Fzf can also auto-complete environment variables:

export **<TAB>
unalias **<TAB>
unset **<TAB>

search hidden file by default

By default, fzf does not search hidden files. In order to search hidden files by default, use the following setting (suppose that you use ag):

export FZF_DEFAULT_COMMAND='ag --hidden --ignore .git -g ""'

See here for more discussions.

Make fzf work under Zsh on macOS

If you are using zsh on Mac with oh-my-zsh, zsh has a plugin to make fzf work with it.

First, add the following setting in .zshrc:

# suppose you have installed fzf to ~/.fzf, change it to what suits you
export FZF_BASE="$HOME/.fzf"

In the .zshrc plugin part, enable this plugin:

plugins=(
  ...
  fzf
)

Source .zshrc to make changes take effect. Fzf should work now on Zsh.

There is one gotcha, Alt + C does not work: it will just print the character ç. If you are using iterm2, it is easy to fix. Open the iterm2 preference settings, go to Profiles -> Keys. In the bottom right of the window, there are different buttons to choose the behaviour of Option key. Just choose Esc+ and everything should be fine.