Many Neovim ex commands can be preceded by a range of lines that the command will operate on. The syntax for ranges can be a little confusing, and to this day I still have to look it up with :help range if I’m doing anything non-standard.

The simplest possible range is the ., which stands for “current line”. It would look like :.s/pattern/replacement. The . between the : and the s is the range, in this case. You normally wouldn’t bother, though because . or “current line” is the default range.

Probably the second most common range you will use is %. It stands for “Entire File”. If you are used to the find and replace dialog in most editors or word processors, you probably expected it to search the “entire file” by default. But it doesn’t, and if you want to do a find and replace across the entire file, you would need to use :%s/pattern/replacement (probably with a /g on the end as described in the next section).

You could also set a specific line number, such as :5s/pattern/replacement to replace the word pattern on line 5. But I would normally use 5G to move my cursor to line five and then do a default range substitution instead.

The name “range” implies that you would can cover a sequence of multiple lines, and you can indeed separate a start and end position using a comma. So, for example, :3,8s/…​ will perform the substitution on lines 3, 4, 5, 6, 7, and 8 (the selection is inclusive at both ends): Here I’ve started a pattern that is highlighting the word hello on lines 3 through 8, but no other lines:

You can also use marks such as 'a as described in the previous chapter to define the start or end of a range.

The most common way you’ll use this is using '<,'>, which specifies the range for “the most recent visual selection”. Luckily, you won’t need to type those characters all that often, because if you select some text using e.g. Shift-V followed by a cursor movement, and then type :, Neovim will automatically take care of copying that range into the command line.

This means that if you want to “perform a substitution in the current visually selected text,” you just have to select the text and type :s/…​. The range will be inserted between the colon and s, so you’ll get :'<,'>s/…​.

If your brain is up for some recursive confusion, you can even use a search pattern to specify one end of the range! In the following example, my cursor was on line 5 when I started the substitution:

The substitution is :,/hello-10/s/hello/foo. All those forward slashes in there make it pretty hard to read (looks like a Unix file path!), but it’s actually easy to write. Let’s break it down from left to right:

There is a ton of other stuff you can do with Vim ranges, but the truth is, most of them only exist to support outdated editing modes. You will likely find that %, '<,'>, and ,/pattern/ cover 95% of your use cases. Read through :help range once to make sure you know what other sorts of syntaxes are available, and don’t be afraid to look them up in the rare cases where one of the above is not sufficient.

You can add “flags” at the end of any substitution (after the last /) to modify how the search and replace behaves. The most common flag you’ll use is g which stands for “global”. You’ll append it more often than not.

By default, substitute only replaces the first instance of a pattern on the line. So if I have a file full of the overly cheerful words hello hello, then the substitution :%s/hello/foo will only replace the first instance on each line:

But if I append /g it will replace all the hello's on each line:

I mentioned earlier that the supremely common use case of “replace everything in the file” is :%s/pattern/replacement/g. The % is "every line", and the g means “every instance in each line”.

There are almost a dozen flags, but the only other useful ones are i, I, and (rarely) c. The first two explicitly ignore case or disable ignoring case in the term being searched for, and you’ll only ever need one or the other depending on whether you have ignorecase set in your options.lua (it defaults to true in LazyVim). The c flag means confirm and is useful if you want to make substitutions in a large file but you know you want to skip some of them. You will be shown each proposed change and can accept or reject them one at a time.

Flags can be combined, so :%s/hello/foo/gc will do a global replace, confirming each one.

You don’t need to memorize this section, but once you get used to substituting, you’ll probably notice that some actions are rather repetitive and monotonous and you’d like to type them faster. Read through these tips so you remember to look them up when you are more comfortable with :substitute.

If you leave the pattern part of a substitution blank, (as in :s//replacement/), it will default to whatever pattern you last searched for or substituted. For example, if you perform these commands in order:

This can save a little typing when you search for a term and then decide you want to replace it, or when you have substituted something in one file and want to substitute it again in another.

If you just use :s without any pattern or replacement, it will repeat the last pattern and replacement you did. But be aware that it will not act on the same range, so if you want to repeat it exactly you’ll need to type the range again.

It also won’t repeat flags, but you can (usually) append the flags directly to :s. For beginners, the most common of these is :%sg, which maps to “repeat the last substitution on the entire file, globally.” This is helpful when you typed :s/long-pattern/long-replacement and expected it to do a global replace, but actually it just replaces the first instance on the current line. :%sg will repeat the substitution the way you intended it. You might also reach for '<,'>sg to replace in the last visual selection.

If you want to reuse “whatever was matched in the pattern” in the replacement, you can use \0 in the replacement string. This is particularly useful when you are using a regular expression that could potentially match different things.

For example, imagine I have the following file:

For some reason, I want to add an adjective between the first and second words. This can be accomplished with the command :%s/[hH]ell\S* /\0green /:

That command might be a little intimidating if you aren’t comfortable with regular expressions, so I’ll break it down again:

You can even reuse part of the pattern in the replacement. To do this, place the part you want to reuse between \( and \). Then use \1 to represent whatever was matched between brackets in the replacement portion.

This is easier to understand with an example. If we start with the same three line example as above, we can use the substitution :%s/hell\(\S*\)/green\1 and blue\1/i to cause the following nonsense substitution:

The \(\S*\) matches the same thing as \S* but it stores the result in a capture. Then when we want to reuse the capture in the replacement, we use \1 to refer back to whatever was captured on that match.

LazyVim ships with a plugin called Grug-far.nvim to do a global find and replace in all files in the project. Without grug-far, you would probably (unenthusiastically) do this from the command line using sed, the stream-oriented evolution of ed that I mentioned.

Grug-far is a lightweight UI wrapping ripgrep, a command line tool I’ve mentioned before. But that UI is pretty handy, as ripgrep has some arcane arguments.

To show the Grug-far UI, use the keyboard shortcut <Space>sr, where the mnemonic is r for replace. A window will open up on the right:

You can navigate around this window using all the normal Vim motions, but you’ll mostly just need j and k to jump between fields.

The search field can accept any regular expression. Because this is using ripgrep under the hood, it is a slightly less arcane regex syntax. The Files Filter field is used to isolate your search to a specific path or file extension, and accepts standard shell glob syntax.

As you fill in the form entries, Grug-far instantly previews the proposed changes in a live-updating widget:

After you have inserted the search and replace text, you will need to press Escape to return to Normal mode. If all the results in the preview area look acceptable, simply hit \r to perform the replacement.

You also have the option to tweak the search results if some of them don’t match your needs. Use any standard motions to navigate the preview window. If there are matches that you don’t want to change, just use dd to delete them outright. Alternatively, feel free to edit any line, right in the preview window, to make it look the way you want.

Once you are satisfied with the preview, use \s instead of \r to sync the changes you’ve made with their original source files.

You can also jump to the source file of a preview result by placing your cursor over it and hitting Enter.

Grug-far keeps track of your recent search and replace operations and allows you to revisit them with the \t keybinding. Navigate between them with standard motions and use Enter to reuse one of them.

There are a few other useful keybindings in a menu you can pop up with g?, which I’ll leave you to peruse at your leisure.

The :substitute command isn’t the only one that can operate on multiple lines at once, with a range. In fact, if you just want to write a few lines out to a separate file, you can pass a range to :write. The easiest way to do this is to select the range in Visual mode and type :write <filename>. Neovim will automatically convert it to :'<,'>write and only save only those lines.

To display the command line editor, type Control-F while the little Cmdline window is focused. Or, if you are currently in Normal mode, type q:. This latter is not related to the “record to register” command typically associated with q. It is instead “Open the editable command line window”.

This window is basically what happens when the normal command line editor marries a normal Vim window and spawns a magical superpower command line window.

The new magic window shows up at the bottom of the current buffer, just above the status bar, and it contains your entire command line history (including searches and substitutions):

Use Control-u to scroll up this baby and you’ll see every command you ever typed. You can even search it with ? (search backward is probably more useful than search forward since your commands are ordered by recency).

To run any of those old commands, just navigate your cursor to that line and press Enter. Boom! History repeats itself.

Or you can enter a brand new command on the blank line at the bottom of this magic command window (remember Shift-G will get you to the bottom in a hurry).

You will find this window is devilishly hard to escape, though. The escape key doesn’t work, because it’s reserved for escaping to Normal mode while editing in the window. The secret is to use Control-C to close it, although other window close commands such as <Space>wq will also work. You can even run :q from inside the command line window.

Most importantly, you can use normal Vim commands to edit any line in this window. Just navigate to the line, use whatever mad editing skills you have (including other command-mode commands such as :s) to make the line look the way you want it to, return to Normal mode, and press Enter. The edited command will execute.

Recall that the q command can record a sequence of commands to a register for later playback. And the :norm command can be used to apply a sequence of commands to a range of lines. The fact that you can p a register that has a recording in it means there are several ways you can later apply a recording to a range of lines using :norm:

The :norm command operates on a range of lines, and Neovim ranges must be contiguous lines. It’s not possible to execute a command on e.g. lines 1 to 4 and 8 to 10, but not 5 to 7 (other than running :norm twice on different ranges).

Sometimes, you want to run a command on every line that matches a pattern. This is where the :global command comes in.

The syntax for :global is essentially :<range>global/pattern/command, although you can shorten it to :<range>g/pattern/command. The pattern is just like any Vim search or substitute pattern.

The command, however, is kind of weird. Technically, it’s an “ex” command, which means “many but not all of the commands that come after a colon, but mostly ones you don’t use in daily editing so they are hard to remember”.

The most common example is “delete all lines that match a pattern”, which you can do with :%g/pattern/d.

Another popular one is substitute, which you already know. If you precede your substitute with :%g/pattern, you can make it only perform the substitution on lines that match a certain pattern. This pattern can be different from the one that is used in the substitution itself. Consider the following arcane sequence of text:

What a mess! This is obviously meant to be easy to write, not easy to read. If we wanted it to be slightly easier to read, we’d probably write :%global/^f/substitue/ba[rt]/glib.

This command means “perform a global operation on every line that starts with f. The operation in this case should be to replace every instance of bar or bat with the word glib.”

In my opinion, the most interesting use of :global is to run a Normal mode command on the lines that match a pattern. This effectively means mixing :global with :normal, as in :%g/pattern/norm <some keystrokes>.

As just one example, this will insert the word “world” at the end of every line that starts with “hello”:

You can also use global to perform a command on every line that does not match a pattern. Just use g!/ instead of g/

I don’t use :global nearly as often as I use :norm. But when I do, it is a hyper-efficient way to cause massive changes in a file. It takes some getting used to, and you’ll probably be looking up the syntax the first few times you need it, but it’s a really terrific tool to have in your toolbox.

This chapter was all about bulk editing text. We started with substitutions using the :s[ubstitute] ex command, and then took a tour of the UI for performing find and replace across multiple files using the Grug-far plugin.

Then we learned how to perform commands on multiple lines at once using :norm and :global, and earned a quick but comprehensive introduction to the command line editing window.

In the next chapter, we’ll learn several random editing tips that I couldn’t fit anywhere else.