16.10.3 Replace Commands and Lax Matches

This subsection describes the behavior of replace commands with respect to lax matches (see Lax Matching During Searching) and how to customize it. In general, replace commands mostly default to stricter matching than their search counterparts.

Unlike incremental search, the replacement commands do not use lax space matching (see lax space matching) by default. To enable lax space matching for replacement, change the variable replace-lax-whitespace to non-nil. (This only affects how Emacs finds the text to replace, not the replacement text.)

A companion variable replace-regexp-lax-whitespace controls whether query-replace-regexp uses lax whitespace matching when searching for patterns.

If the first argument of a replace command is all lower case, the command ignores case while searching for occurrences to replace—provided case-fold-search is non-nil and search-upper-case is also non-nil. If search-upper-case (see search-upper-case) is nil, whether searching ignores case is determined by case-fold-search alone, regardless of letter-case of the command’s first argument. If case-fold-search is set to nil, case is always significant in all searches.

In addition, when the second argument of a replace command is all or partly lower case, replacement commands try to preserve the case pattern of each occurrence. Thus, the command

M-x replace-string RET foo RET bar RET

replaces a lower case ‘foo’ with a lower case ‘bar’, an all-caps ‘FOO’ with ‘BAR’, and a capitalized ‘Foo’ with ‘Bar’. (These three alternatives—lower case, all caps, and capitalized, are the only ones that replace-string can distinguish.) Note that Emacs decides whether to up-case or capitalize the replacement text by analyzing each word in the text being replaced, and will preserve the letter-case of the replaced text only if all of its words use the same letter-case. Thus, the command

M-x replace-string RET foo bar RET baz quux RET

replaces ‘Foo Bar’ with ‘Baz Quux’ because both words in ‘Foo Bar’ are capitalized. By contrast, the same command replaces ‘Foo bar’ with ‘baz quux’, i.e. it leaves the letter-case of the replacement text unchanged, since the two words in ‘Foo bar’ use different capitalization. What exactly is considered a “word” depends on the syntax tables that are in effect in the current buffer (see Syntax Tables in The Emacs Lisp Reference Manual); thus, ‘Foo_Bar’ is two words in Text mode, but could be a single word in some major mode that supports a programming language.

If upper-case letters are used in the replacement string, they remain upper case every time that text is inserted. If upper-case letters are used in the first argument, the second argument is always substituted exactly as given, with no case conversion. Likewise, if either case-replace or case-fold-search is set to nil, replacement is done without case conversion.

The replacement commands by default do not use character folding (see character folding) when looking for the text to replace. To enable character folding for matching in query-replace and replace-string, set the variable replace-char-fold to a non-nil value. (This setting does not affect the replacement text, only how Emacs finds the text to replace. It also doesn’t affect replace-regexp.)