Replacing a Word in a Neovim Buffer

It is a common task to search and replace all occurrences of a word within the current buffer, and as you might expect Vim provides a variety of tools that can be used to do so.

For example, the following buffer contains an excerpt from the Zen of Python:

Suppose we want to change all occurrences of is better to is way better.

We have an entire chapter discussing search and replace, but to summarize the general pattern for searching and replacing is:

:[range]s/{pattern}/{replacement}/[flags]

where:

Putting this all together we get the command:

:%s/is/is way/

Pretty simple. Now, let's enter our command into the editor:

and finally after hitting Enter to execute it we get:

As expected, each occurrence of is has been replaced with is way. Writing patterns can sometimes require a little bit of trial and error, so if the final result is not as expected you can simply hit u to return to the original text and try again. Let's go ahead and undo the changes we just made, which will prepare the buffer for the next section:

Now let's look at a couple of variations that can be useful in some situations.

Replacing the Word Under the Cursor

The first variation we will look at allows us to save a few keystrokes by selecting the text we want to replace, rather than typing it. Starting from our original buffer, the first step is to move the cursor to the word that we want to replace. We can do this in normal mode by pressing w to move forward one word text object:

Now, pressing * selects all occurrences of the word under the cursor.

Now that we have selected the text to replace, we can simply replace the {pattern} portion of the command, and Vim will know to insert the selected text for us:

:%s//is way

As we saw in the first example, each occurrence of is has been replaced with is way.

Replacing Selected Text

In the previous example, hitting * selected the word under the cursor, which became the search {pattern}. This behavior also applies to visual selections in general:

Starting from our original buffer:

As in the previous example, let's first move forward one word text object, hit v to start a visual-selection, then we to move the cursor to the end of the next word:

With our text selected, let's hit * as before to select all matching text in the current buffer:

and finally execute the search:

:%s//is way better

Replacing Text from a Register

We have now see a few different ways that we can define the {pattern} that we want to search for. Now, let's take a look at how we can use the contents of a register to define the {replacement} text.

Starting from the same buffer as in the previous examples, note that we have already stored the replacement text in register A:

Although in normal mode we access the content of a register contents using "{register}, the search is executed in command-line mode we access register contents somewhat differently:

where C-R is shorthand for "Ctrl-R". Here are the steps required to use this:

1. Press : to open the command-line
2. Press %s to indicate that we want to search over the entire buffer content
3. Type /is to define the text to search for
4. Type / to start defining the replacement text
5. Press and hold the Ctrl key while typing r
6. Press a to indicate which register holds the replacement text

At this point, the contents of register a have been inserted into the command-line. At this point you can edit that content further if necessary, then finally execute the command:

Although replacing text from a register may not be a daily activity, this can be convenient in cases where the replacement text is complicated, or when we need to search and replace several patterns with the same replacement text.