Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Buffers, Windows and Tabs

The Argument List and the Quickfix List

Run commands across many files with the argument list and the quickfix list: :args, :argdo, :vimgrep, :grep, :copen, :cdo, location lists and errorformat.

Sooner or later you must change something in many files: rename a function, fix a deprecated call, read every compiler error. Vim has two lists for this. The argument list is a list of files you name. The quickfix list is a list of positions (file, line, column, message), usually produced by a compiler or a search.

Both feed commands that visit each item in turn, so a repetitive edit across 50 files becomes two commands.

The argument list

Files you pass on the command line form the argument list: vim *.md puts every Markdown file in it. Inside Vim:

Command Effect
:args Show the list; [x] marks the current file
:args src/**/*.js Replace the list (the ** wildcard recurses)
:argadd file Add a file; :argdelete file removes one
:next / :prev Edit the next / previous file
:first / :last Jump to the ends
:argdo cmd Run cmd in each file

A classic bulk rename:

VIM
:args src/**/*.js
:argdo %s/\<oldName\>/newName/ge | update

The e flag keeps the substitute quiet in files without a match, \< and \> match word boundaries, and | update saves a file only if it changed. Without hidden and update, Vim would refuse to move to the next file. Use :argdo when you can name the files up front.

The quickfix list

Quickfix was born for compiler errors: :make runs your build tool and collects every file:line: message into a list. Today it is the general-purpose list of places.

Command Effect
:copen / :cclose Open / close the quickfix window
:cnext / :cprev Next / previous entry (:cn, :cp)
:cfirst / :clast First / last entry
:cc 7 Go to entry 7
:clist Print the list in the command area
:colder / :cnewer Go through earlier lists (Vim keeps ten)

In the quickfix window press Enter on a line to jump to its location. Many people map ]q and [q to :cnext and :cprev. Neovim has these by default.

Filling the list

  • :make runs makeprg and reads output through errorformat.
  • :vimgrep /pattern/ **/*.py searches files with Vim's own regex engine. Add j (/pattern/j) to avoid jumping to the first match.
  • :grep pattern calls the external grepprg program. Setting set grepprg=rg\ --vimgrep and set grepformat=%f:%l:%c:%m makes it use ripgrep, which is much faster.
  • :cexpr system('cmd') fills the list from any command's output.
  • Plugins and Neovim's LSP client fill it with references and diagnostics.

Acting on every entry: :cdo and :cfdo

:cdo cmd runs cmd on each entry (each match), and :cfdo cmd runs it once per file that has an entry. Together with a search they give you project-wide refactoring with a review step:

VIM
:vimgrep /TODO(bob)/j **/*.ts
:copen
:cdo s/TODO(bob)/TODO(alice)/ | update

You can first look at the list in the quickfix window, remove entries you do not want (dd works in the list if modifiable, or filter with the Cfilter plugin that ships with Vim: :packadd cfilter then :Cfilter /pattern/), and only then run :cdo. :cfdo %s/a/b/g | update replaces in every file containing a match.

JS Stand-in: build a quickfix list from files

Press Run (or Ctrl + Enter) to see the console output here.

No output.

errorformat: teaching Vim to read errors

errorformat is a list of patterns, a bit like scanf, telling Vim how to extract the file, line, column and message from tool output. Common items: %f file, %l line, %c column, %m message. For output like src/app.c:12:5: error: expected ';' the pattern is %f:%l:%c: %m. You set it per tool, often through a compiler plugin (:compiler gcc) or an ftplugin file. Use :cexpr or :cfile errors.txt to test a format on saved output.

JS Stand-in: a tiny errorformat parser

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Location lists

A location list is a quickfix list owned by one window. Commands start with l instead of c: :lvimgrep, :lgrep, :lopen, :lnext, :ldo. Use them when two windows should each keep their own list (for example, diagnostics for the current buffer and a project search in the quickfix list). :lopen opens the location list for the current window.

Argument list or quickfix?

Use the argument list when you can describe the files with a glob and want the same command on all of them. Use quickfix when the places come from a search or compiler, or when you want to review and trim the targets before running :cdo. Both depend on commands being safe to repeat, so test the substitution on one entry first and use :wa or | update to save.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between :cdo and :cfdo?

    :cdo visits each quickfix entry (match). :cfdo visits each file in the list once, which suits whole-file commands like :%s.
  2. 2. Which command replaces the argument list with every JavaScript file below src?

    :args with a pattern sets the list; ** matches directories recursively.
  3. 3. What does the j flag do in :vimgrep /pat/j **/*.py?

    Without j, Vim jumps to the first match after filling the list.
  4. 4. Which option tells Vim how to parse compiler output into quickfix entries?

    errorformat holds the patterns; makeprg is the command that :make runs.

Summary

  • The argument list (:args, :argdo) holds files you name; the quickfix list holds positions from searches and builds.
  • Fill quickfix with :make, :vimgrep, :grep (try ripgrep) or :cexpr.
  • :cdo acts per entry, :cfdo per file; add | update to save.
  • errorformat parses tool output; location lists are window-local quickfix lists.

Next: Your vimrc and Options