how to use fzf in vim?
One thing that modern text editors/ IDEs got right that Vim didn't is how easy it is to find files and to find in files with modern editors/IDEs. In this article, I will show you how to use FZF.vim to make searching in Vim as easy as searching in modern editors/IDEs.
Here are the things I will cover:
Warning: when using FZF, please fasten your seatbelt, because it can get REALLY fast. 🚗 🔥 🔥
Before we start, we need to download FZF and ripgrep. Follow the instruction on their github repo. If you have homebrew, you can run brew install fzf and brew install ripgrep. The commands fzf and rg should be now available.
In my .zshrc (.bashrc if you use bash), I have these:
FZF does not use ripgrep by default, so we need to tell FZF to use ripgrep with FZF_DEFAULT_COMMAND variable.
Pay attention to -m in FZF_DEFAULT_OPTS. This option allows us to make multiple selections (with Tab or Shift-Tab). You don't have to use it, but I think it is helpful to be able to select multiple files. It will come in handy when you want to perform search and replace in multiple files - which I'll cover in just a little bit :). The remaining options are optional. To learn more, check out fzf's repo or man fzf.
At minimum we should have export FZF_DEFAULT_COMMAND='rg'.
After installing fzf and rg, let's set up Vim. I am using vim-plug plugin manager in this example, but you can use anything.
To set up FZF in Vim, add these inside your .vimrc plugins. We will be using FZF.vim plugin (created by the same FZF author). The second line ensures that we have latest FZF.
For more info, you can check out this README page from FZF.vim repo.
Let's go over syntax so we can search more efficiently. Fortunately for us, there aren't many to learn.
We can mix and match the above. For example, ^hello | ^welcome friends$ searches for phrase starting with either "welcome" or "hello" and ending with "friends".
To search for files inside Vim using FZF.vim plugin, we can use :Files method. Run :Files from Vim and you'll be prompted with FZF search prompt. Pretty cool!
FZF.vim file finder is best used with a mapping. I've used
To search inside files, we can use FZF.vim's :Rg command. Alternatively, we can use :Ag (The Silver Searcher). For this article, I will use :Rg.
Mine is mapped to
Side note: FZF.vim :Rg option also searches for file name in addition to the phrase. If you think this is an issue, check out this comment. I added this in my .vimrc:
With the above, every time we invoke Rg, FZF + ripgrep will not consider filename as a match in Vim.
FZF.vim provides many other search commands. You can check them out here.
Here's what my FZF mappings look like:
Internally, Vim has two ways to search in files: :vimgrep and :grep. :vimgrep uses vim's built-in grep and :grep uses external tool which you can reassign using 'grepprg'.
For example, if we want to search for "iggy" with :grep, we can run :grep "iggy" . -R (you may notice that Vim's :grep syntax is similar to terminal grep command; this is because :grep by default runs grep -n $* /dev/null on unix-based machine). The command above will search for string "iggy" recursively (-R) from current location (.).
Vim allows us to change the program used by :grep. We can tell Vim to use ripgrep instead of grep by adding this inside our vimrc:
Now when we run :grep inside Vim, it will run rg --vimgrep --smart-case --follow instead. For more information what the options above mean, check out man rg. I can now run a more succinct command :grep "iggy" instead of :grep "iggy" . -R.
Vim :grep command uses quickfix to display results. I won't go over quickfix here because it's outside this article's scope. We can use :copen to display quickfix window and :cclose to close quickfix window. Try it!
You might wonder, "Well, this is nice but I never used :grep in Vim, plus can't we just use :Rg to find string in files? When will I ever need to use :grep?"
That is a very good question. The answer to "why do we need grep in Vim?" is that it will let us to do what I'll going to cover next: search and replace in multiple files.
Modern text editors like VSCode makes it very easy to search and replace string across multiple files. If I may confess, in the beginning when I had to search/replace string in multiple files, I used VSCode because doing it in Vim, although possible, takes too long... until now.
I will show you two different tricks to easily do search and replace phrases across multiple files in Vim.
The first method is to replace ALL matching phrases in our project. We will need to use :grep. Let's say you want to replace all instance of "pizza" with "donut". Here's what you do:
That's it? Yup! That's it. Let me break down the steps:
Let's discuss the second way.
The second method is to search and replace in select multiple files instead of all files using buffers. Here we can choose which files we want to perform select and replace.
Our command :bufdo %s/pizza/donut/g | update looks similar to :cfdo %s/pizza/donut/g | update. That's because they are. Instead of performing substitution on all quickfix (cfdo) entries, we perform our substitution on all buffer (bufdo) entries.
FZF.vim is a game-changer. I can't imagine using Vim without it. This article shows how to set up necessary tools and configs to get FZF running in Vim. I also shared some tips to perform more complicated searches, like search-and-replace.
Once everything is set up, we can now search quickly in Vim like modern editors/ IDEs.
Hope you find this helpful. Keep improving. Keep hacking. Keep inventing.
Happy coding!
- 1068. Everything. Free • Proprietary.
- 113. DocFetcher. Free • Open Source.
- fzy. Free • Open Source. File Search Utility.
- skim (fuzzy finder) Free • Open Source. Mac.
- Search Text In Files. Freemium • Proprietary. File Search Utility.
- Percol. Free • Open Source. Terminal Emulator.
- Peco. Free • Open Source.
- GoToFile. Freemium • Proprietary.
As a developer, I’m often bouncing between numerous files, looking for a specific item in a massive codebase, or trying to remember that arcane command I ran once months ago.
There are a handful of fuzzy find tools, either from built-in editor features or via the shell, but they often suffer from unfortunate limitations. Whether slow performance or having cache results get out of date, they often require accepting tradeoffs.
Enter FZF, a modern fuzzy finder written in Go that is not only incredibly fast but also very customizable.
With shell bindings and the ability to tie into Vim, it’s sped up our workflow at Headway quite a bit. Searching for a file by name in a project is nearly instantaneous, and it’s easy to pull up a command in your shell history with a few keystrokes.
I manage my Vim plugins using vim-plug which is a simple manager that installs plugins in parallel. It also has the ability to run post-install hooks to manage external libraries. Using it to install and manage FZF is straightforward:
In your .vimrc:
Running :PlugInstall in Vim will then copy FZF into the .fzf directory in your home folder and then run its post-install script to configure the native executable. FZF comes with basic Vim bindings out of the box, but I like to make a few changes:
In your .vimrc:
This maps the FZF search to Ctrl-F, and sets up hotkeys for opening splits in Vim similar to others I’m used to using. With only those few lines, searching for any file within the root directory becomes a breeze.
When vim-plug installs FZF, it also makes it available for use on your PATH as well. With a few entries in Zsh’s config, we can tie command history search into FZF:
In your .zshrc:
This sets up Zsh’s history search on Ctrl-R and then runs the FZF zshell script to configure FZF for it.
Now that we have our fuzzy find in place, there’s a good chance we’ll want to exclude certain entries from the results. Library dependencies, the .git directory, and others can be easily left out by setting the FZF_DEFAULT_COMMAND environment variable:
In your .zshrc:
Things you can do with fzf and Vim.
fzf itself is not a Vim plugin, and the official repository only provides the basic wrapper function for Vim. It's up to the users to write their own Vim commands with it. However, I've learned that many users of fzf are not familiar with Vimscript and are looking for the "default" implementation of the features they can find in the alternative Vim plugins.
This repository is a bundle of fzf-based commands and mappings extracted from my .vimrc to address such needs. They are not designed to be flexible or configurable, and there's no guarantee of backward-compatibility.
Because you can and you love fzf.
fzf runs asynchronously and can be orders of magnitude faster than similar Vim plugins. However, the benefit may not be noticeable if the size of the input is small, which is the case for many of the commands provided here. Nevertheless I wrote them anyway since it's really easy to implement custom selector with fzf.
fzf.vim depends on the basic Vim plugin of the main fzf repository, which means you need to set up both "fzf" and "fzf.vim" on Vim. To learn more about fzf/Vim integration, see README-VIM.
fzf#install() makes sure that you have the latest binary, but it's optional, so you can omit it if you use a plugin manager that doesn't support hooks.
(1: Helptags will shadow the command of the same name from pathogen. But its functionality is still available via call pathogen#helptags(). ↩)
Every command in fzf.vim internally calls fzf#wrap function of the main repository which supports a set of global option variables. So please read through README-VIM to learn more about them.
Some commands will show the preview window on the right. You can customize the behavior with g:fzf_preview_window. Here are some examples:
A few commands in fzf.vim can be customized with global option variables shown below.
Each command in fzf.vim is backed by a Vim function. You can override a command or define a variation of it by calling its corresponding function.
(We can see that the last two optional arguments of each function are identical. They are directly passed to fzf#wrap function. If you haven't read README-VIM already, please read it before proceeding.)
This is the default definition of Files command:
Let's say you want to a variation of it called ProjectFiles that only searches inside ~/projects directory. Then you can do it like this:
Or, if you want to override the command with different fzf options, just pass a custom spec to the function.
Want a preview window?
It kind of works, but you probably want a nicer previewer program than cat. fzf.vim ships a versatile preview script you can readily use. It internally executes bat for syntax highlighting, so make sure to install it.
However, it's not ideal to hard-code the path to the script which can be different in different circumstances. So in order to make it easier to set up the previewer, fzf.vim provides fzf#vim#with_preview helper function. Similarly to fzf#wrap, it takes a spec dictionary and returns a copy of it with additional preview options.
You can just omit the spec argument if you only want the previewer.
The following example implements GGrep command that works similarly to predefined Ag or Rg using fzf#vim#grep.
fzf#vim#complete is a helper function for creating custom fuzzy completion using fzf. If the first parameter is a command string or a Vim list, it will be used as the source.
For advanced uses, you can pass an options dictionary to the function. The set of options is pretty much identical to that for fzf#run only with the following exceptions:
When fzf starts in a terminal buffer (see fzf/README-VIM.md), you may want to customize the statusline of the containing buffer.
