The Quickfix List

A structured list for navigating compiler errors, search results, LSP diagnostics, and other code locations in Vim/Neovim.

The quickfix list is a core feature in Vim and Neovim designed to manage a structured collection of locations within a codebase. While originally developed to speed up the “edit-compile-edit” cycle by saving error messages from a C compiler, it is now used as a unified workflow for search results, LSP diagnostics, lint output, and test results.

Populating the Quickfix List

The list can be populated through several internal and external tools:

  • Compilation: The :make command invokes an external compiler, parses its output using the 'errorformat' setting, and builds the list from the results.
  • Project-wide Search: Both :vimgrep (using Vim’s internal engine) and :grep (a wrapper for external tools like grep or ack) populate the list with matches.
  • LSP Diagnostics: In Neovim, language server diagnostics can be sent to the quickfix list using Lua commands like vim.diagnostic.setqflist().

You can interact with the quickfix list using the following Ex commands:

  • :copen and :cclose: Opens and closes a window displaying the list.
  • :cnext and :cprev: Jumps to the next or previous entry in the list.
  • :cfirst and :clast: Jumps to the very first or last entry.
  • :cc [n]: Jumps to a specific entry by its number.
  • :cnfile and :cpfile: Jumps to the first match in the next file or the last match in the previous file.

In Neovim 0.11, several default keybindings were introduced to navigate the list more easily, such as ]q for next and [q for previous.

Advanced Operations (cdo and cfdo)

The quickfix list is a powerful tool for refactoring and batch processing across multiple files:

  • :cdo {cmd}: Executes a command on every individual item in the quickfix list.
  • :cfdo {cmd}: Executes a command once for each file represented in the list.
  • These commands are often paired with :update to save changes across an entire project after a substitution.

List History and Management

  • History: Vim keeps track of the last ten quickfix lists. You can navigate between them using :colder to go to an older list and :cnewer to return to a more recent one.
  • Location Lists: Unlike the quickfix list, which is global to the entire editor, a location list is local to a specific window. Most quickfix commands have a location list equivalent prefixed with ‘l’ (e.g., :lopen, :lnext).