A quick guide to quickfix
Or, how to use grep from within Vim, without plugins
Welcome, Vim morlocks! I’m Nat Bennett — writer, consultant, full-time command-line resident — and you’re reading Mastering Neovim, a newsletter that aims to arm you in the war on graphical IDEs. (And help you write code faster and stuff.)
I have an outline for the book this newsletter will become. Take a look to see where we’re going, and leave questions and comments.
This newsletter will always be free. If you subscribe, you’ll get a 50% discount code for the final artifact when it’s published. You’ll also get early access to drafts, notes, and my deep gratitude — I’m able to write more and better when I know people are reading.
This is part of an ongoing sub-feature about codebase navigation. Until recently, if I needed to find a specific string in a codebase, I would switch tabs or background Neovim (with ctrl-z), search, and then open the file directly with :e. But it’s possible to do that entire workflow from within the editor, using a feature called “quickfix.” (Also called “Quickfix,” “QuickFix,” “Quickfix mode,” and “the Quickfix view.”)
Quickfix is more general purpose than just grepping, but today we’ll focus on that use case.
Quickfix shows you a list of locations in a codebase and lets you go to them. You can get that list of locations from a lot of different sources but the navigation once you get them into a quickfix window is the same.
Without any plugins or anything, there are two basic ways to get a quickfix list: grep and make. You can see what grep produces by running an Ex command like this:
:gr zsh . -R(Substitute whatever search pattern you want for “zsh”)
You should see a list of filepaths and an input prompt. If you hit ENTER you’ll open up the first result in the list. By default quickfix mode assumes that you’re working through a list of errors (from, say, a compiler) and you want to deal with them one at a time.
But for something like grep, you might want to navigate to a different result. There are a couple of ways you can do that.
From the raw quickfix list you can type this command to get a specific result line.
:cc 4That will return the fourth grep result. Then when you hit ENTER you’ll open that file. This is also awkward though because there aren’t line numbers in this raw quickfix view, so you have to count by yourself like an animal.
:cope-ing with quickfix
There are a bunch of ways to navigate around in this list and get numbers for them, but what you probably want to do instead is to open the quickfix window with this command.
:copeThis feeds that quickfix list output into a window that you can navigate around in using normal Vim cursor commands. Then you hit “enter” on the one you want, and it opens.
So, to recap
“:gr [pattern] . -R” (or another command that creates a quickfix list)
“:cope” to open that list in the quickfix window
Use cursor navigation, /search, etc. to move to the line with the file you want
ENTER to open that file
There are ways to clean this interaction up, or to use tools other than :grep with this command, and a lot of search and file navigation plugins will do that for you. But this is the basic component that’s powering plugins like Ag.
Notes and links
This is largely just restating some key points from the Vim :help pages about Quickfix.
I use this Ag plugin for search instead of trying to :grep directly.
I use Ag because it’s fast, and its defaults better match what I usually want than grep’s.
But also because I’m old and haven’t gotten around to switching to the platinum searcher.
I’ll get into more detail about this at some point but I emphasize window in this point because it’s a kind of primitive concept in Vim.
Those things that start with :? There’s a word for it — those are Ex commands.
A note on the Vim documentation, or, “just what is a mode, anyway?”
At some point I should write specifically about the Vim docs, because they are simultaneously
comprehensive
precise
helpful
and strange
They tend to assume that you know (or at least are interested in) the fundamentals of the underlying model of Vim editing, and have a tendency to drop details like that quickfix “inspired by the quickfix option of the Manx’s Aztec C compiler on Amiga” before explaining what quickfix does.
Did you know that Vim has thirteen modes? (Seven BASIC modes and six ADDITIONAL modes that are variations on the BASIC modes.)
“Quickfix” isn’t one of them, but the documentation for it refers to it as a “special mode.” So it’s a mode in the program but not technically a Vim input mode. I’ll probably look more into what exactly a “mode” is in the near future.