💾 Archived View for dmerej.info › en › blog › 0040-fzf-for-the-win.gmi captured on 2023-01-29 at 16:06:31. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2022-07-16)

-=-=-=-=-=-=-

2017, May 17 - Dimitri Merejkowsky
License: CC By 4.0

Last month, I heard about fzf[1] for the first time.

1: https://github.com/junegunn/fzf

Today, it has become one of my favorite tools and I can no longer imagine working on a computer without it installed.

Let me tell you what happened. 







First, I'm going to describe quite a few different tools I was using, both in my shell (zsh), and in my text editor (neovim).







Then, I'll show you how and why I replaced all this tools with `fzf` and how it allowed me to have a better workflow.







The dark times (before fzf)







dark times [IMG]










Finding files in folders







Let's say I was trying to edit `FooManager.java`, buried deep in a `src` folder.







My zsh history looked like this:







$ find -name foo
# Oups, forgot to put the dot
$ find . -name foo
# Oups, the file is not named 'foo' exactly, I need
# to add globs
$ find . -name *foo*
# Oups, I need to add quotes to prevent the shell
# from expanding the globs:
$ find . -name "*foo*"
# Oups, find is case-sensitive by default, so I need
# `-iname` instead of `-name`
$ find . -iname "*foo*"
src/main/java/com/example/foo/FooManager.java
# Now I can copy/paste the file path and
# edit the file in vim:
$ vi <shift-ctrl-v>







Phew! That's a *lot* of keystrokes for such a basic task!







Browsing zsh history







Going up and down







I would use `CTRL-N` and `CTRL-P` to navigate up and down the history.







For instance, if I've typed the following list of commands:







$ ls foo
$ ssh server1
$ ls bar
$ ssh server2







I could press `CTRL-P` three times to get `ssh server1`, and then hit `CTRL-N` to get `ls bar`.







Using the arrow keys







There's an other trick I would use with zsh. Instead of listing all the commands in chronological order, you can tell zsh to only display commands that start with the same characters as your current line.







So I had something like this in my `~/.zshrc`:







bindkey '^[[A' history-beginning-search-backward
bindkey '^[[B' history-beginning-search-forward







And that meant I could do:







$ ssh <up key>







and then continue to press 'up' until I found the correct server. And if I went too far, I could just press 'down'.







Looking for a specific command







Sometimes I wanted to re-enter a command but I knew it was far down the history list. Or, I remembered parts of the command, but not how it started.







So rather that hitting `CTRL-P` a bunch of times, I would use `CTRL-R` instead.







But using `CTRL-R` properly is not obvious. With my `zsh` config, I had to:












Also, sometimes I would get the dreaded `failing bck-i-search` message which often meant I had to start over.







In neovim







List buffers







In `neovim` you can use `:list` to list all the open buffers.







There are displayed like this:







  1 %a + foo.txt
  3 #h   bar.txt
 10  a   baz.txt







Every buffer has a number. The columns between the number and the  name contains info such as whether the buffer is active or hidden, if it's modified and so on.







The `#` sign mark the "alternate" buffer, that is, if you press `:b#` you'll go back and forth from the alternate buffer to your current buffer.







You can switch to a buffer by using `:b<num>`, where `<num>` is the buffer number.







And you can also use tab completion after `:b` to list all the buffer names containing a certain pattern.







So, to open the buffer 'baz.txt', I would type:







:b bar
<tab>
" nope, I don't want bar.txt
<tab>
" ok, I got baz.txt
<enter>







This worked quite well, except sometimes I would get far too many matches, and then I would spend quite a long time hitting `<tab>` to find the buffer I wanted.







Browsing old files







neovim keeps a list of all the file names you have edited.







You can display the list by using `:oldfiles`.







It looks like this:







1: /home/dmerej/foo.txt
2: /home/dmerej/bar.txt
3: /home/dmerej/src/spam/eggs.py
-- More --







You have to press `enter` to see the rest of the list, and after you've pressed `enter`, there is no way to go back.







You also can't search in the list.







And if you want to open one of the files, you have to use `:browse oldfiles`, carefully remember its index, and when prompted, type the number and press `<enter>`.







This is a bit tedious while all you want is a simple "Select From Most Recently Used" feature that almost every other text editor has :/







Looking for patterns







patterns [IMG]










This is a very general technique you can use when trying to improve your workflow. Look for a pattern and then find one way to deal with it that you can re-use everywhere.







So what's the pattern in all the tools I just showed you?







In every single case (from browsing the neovim buffers or trying to find something in `zsh` history), we have a list (more or less sorted), and we want to select *one and only one* element from the list.







We care deeply about interactivity: this means it should be easy to recover from some mistakes, such as typing the letters in the pattern in the wrong order, making typos, or not caring about case sensitivity.







Here's where `fzf` comes in.







fzf for the win!







`fzf` does only one thing and it does it well. You are supposed to use it with a shell pipe, like this:







$ some-source | fzf







Here `fzf` will use a few lines of text, displaying a list of elements, returned by the `some-source` command. (By default the last `n` elements).







But while you are entering the pattern to filter the list of matches, it will update the list in real time.







It will color the part of the lines that matches, and will allow you to enter "fuzzy" patterns (allowing for typos and the like)







You can see it in action on asciinema






Note that:

































There's tons of info in `fzf` man page and in the wiki











2: https://github.com/junegunn/fzf#fuzzy-completion-for-bash-and-zsh






Installation







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







Note that `fzf` is written in Go which means:












More precisely, it means you can start select things as soon as fzf starts, *while fzf is still processing its input*.







fzf out of the box







zsh history







You can configure `fzf` so that it runs when you hit `CTRL-R`.







Personally, I also tell `fzf` to start when I hit the arrow key:







bindkey '^[[A' fzf-history-widget







I'm so used to using arrow keys to navigate the zsh history that it makes sense to just overwrite the behavior for this case.







Still, `fzf` is a bit overkill when all you want is to re-type exactly the previous command, so I also configured `CTRL-N` and `CTRL-P` to do "dumb" history navigation:







bindkey '^P' up-line-or-history
bindkey '^N' down-line-or-history







Replacing find







By default, when pressing `CTRL-T`, `fzf` will allow to select any file name in the directory, recursively, and when you are done selecting it, it will insert the path after your current line.







So for instance, you can use:







$ vim <ctrl-t>
# Start fzf
# Select Foo.java
# Press enter once, line becomes:
$ vim src/main/java/com/example/foo/Foo.java
# Press enter to edit the file







This is much more efficient than the "run find and copy/paste the results" technique I was previously using :)







fzf and neovim







By default, `fzf` installs a very light wrapper on top of the `fzf` executable.







Instead of the interactive list being displayed in a terminal, it will get displayed in a special neovim buffer, but the rest of the usage (including the keystrokes) will be the same as in the shell version.







I suggest you use fzf.vim[3] which brings you nice commands out of the box such as :







3: https://github.com/junegunn/fzf.vim











After installing the plug-in, all you have to do is to configure some mappings:







nnoremap <leader>p :History<CR>
nnoremap <leader>b :Buffers<CR>
nnoremap <leader>t :Files<CR>







`fzf.vim` also allow you to create your own command using a bit of `vimscript`:







command! -nargs=0 MyCmd :call SelectSomething()

function! SelectSomething()
call fzf#run({
    \ 'source': "my-cmd",
    \ 'sink': ":DoSomething"
    \})
endfunction







Here we define a command named `MyCmd`, that will call the `SelectSomething()` function.







`SelectSomething` in turn will use the output of the `source` argument as `fzf` input, and then will run the `sink` command on the selected element.







Consistency is key







To be honest, I must say that I was already using a fuzzy finder named CtrlP[4].







4: https://github.com/kien/ctrlp.vim






But I decided to stop using it and use `fzf` instead.







That's because s something really nice about using the same tool in my shell and in my editor. It means I only need to learn how to use and configure it once.







But this goes further than that. For instance, in my setup:

















# go to a path relative to the top directory
# of the current git worktree.
function gcd() {
  topdir=$(git rev-parse --show-toplevel)
  if [[ $? -ne 0 ]]; then
    return 1
  fi
  cd "${topdir}/${1}"
}







This is not a coincidence. After all, If I'm doing the same kind of stuff in my editor and my shell, I expect to be able to use similar keystrokes.







Note: I've still have a few things to say about the editor/shell relationship, but this will be done in an other post. (shameless teasing)







Conclusion







So that's my story about `fzf`. It boils down to quite a simple process:












By the way, if this reminds you of the famous Seven habits of effective text editing[5] article by Bram Moolenaar, this is no coincidence either :)







5: http://moolenaar.net/habits.html






Cheers!


----



Back to Index


Contact me