How to replace words in a region using iedit?

Question

I want to replace some words inside a region. I would like to use iedit more than query-replace, but found the following problems (probably because I don't understand its documentation):

1. If I select a region, and then activate iedit, it takes the whole region as the text to change in the buffer.

2. If I don't select any region, it takes the symbol under point as the text to change in the buffer.

There's a function called iedit-toggle-selection, but I don't understand how to use it (by default in C-; and in Spacemacs in M-;). How do you replace, let's say two contiguous words, with some arbitrary text, inside a region (using iedit)?

Answer 1

In Spacemacs once you are in iedit state you can:

• press F to limit the scope to the current function
• press L to limit the scope to the current line
• press J to increase the scope (starting from the current line) one line below
• press K to increase the scope one line above
• navigate between the occurrences with n and N and press TAB to remove an occurrence.

Answer 2

There are a couple ways to do this. (I'm using standard GNU Emacs, not familiar with Spacemacs.)

You can narrow the buffer to the region you are interested in and then use iedit to highlight / change all the visible matches. With this approach you want to mark the relevant region first and call narrow-to-region (C-x n n). Use iedit to make the changes you want and then call widen (C-x n w) to see the whole buffer again. Using narrow/widen this way is handy as it can be used in lots of other cases. Any command that operates on the buffer can be restricted to a smaller region this way.

You can also do it the other way around and start with iedit. Use iedit-mode to highlight all instances of some bit of text you want to change. Then mark a region to restrict the changes and call iedit-mode again. This will un-select all matches outside the region so that you can safely change just the matches you want.

There are some options for restricting the selection once you've called iedit-mode. Use M-H to narrow to the current function or M-I to narrow to the current line.

Answer 3

To restrict iedit to a region, first you need to activate iedit-mode, then select a region and call iedit-mode again:

1. M-x iedit-mode to enter iedit-mode as you normally would.
2. Select the region you want.
3. M-x iedit-mode again to restrict iedit to the selected region.

iedit-toggle-selection can be used to unselect the occurence at point.

In spacemacs, use SPC s e instead of M-x iedit-mode.
Technical note: SPC s e calls evil-iedit-state/iedit-mode, which in turn calls iedit-mode - this is done for integration with evil)