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)?


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.
  • 1
    So: you first select the words to look for, then you enter iedit mode (SPC s e in Spacemacs) and these words are the ones to be changed in the whole buffer. Unless you press L to limit the scope to the current line, and keep pressing J and K, or F to extend the scope. Thank you, @syl20bnr. – El Diego Efe Jun 26 '15 at 17:20
  • @ElDiegoEfe yes that's it. Be sure to consult the documentation file which has an exhaustive list of commands and bindings. – syl20bnr Jun 26 '15 at 17:23
  • Maybe it's my lack of skill in english, but I didn't understand the documentation at first. I still don't get what the iedit-toggle-selection function does. – El Diego Efe Jun 26 '15 at 17:45
  • 1
    When you call iedit-mode it will highlight all matches. You can then jump between then (e.g. with TAB) and un-select (or re-select) individual matches one at a time using iedit-toggle-selection. This is useful if you want to modify most but not all matches. – glucas Jun 26 '15 at 19:19

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.


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)

Your Answer

