replace-string-in-files(3)

NAME

replace-string-in-files - Search and replace strings across files

SYNOPSIS

replace-string-in-files "from-pattern" "to-pattern"


"[find-options] <file-mask> [file-mask] ..." ["starting-path"]

query-replace-string-in-files "from-pattern" "to-pattern"


"[find-options] <file-mask> [file-mask] ..." ["starting-path"]

DESCRIPTION

replace-string-in-files performs a search for a from-pattern and replaces the string with to-pattern in all files that match file-mask in the current directory (or from starting-path) using built in MicroEmacs commands rather than relying on any external executables such as grep(1).

query-replace-string-in-files is identical to replace-string-in-files except the user is prompted to accept each potential replacement.

find-options


Defines the options that are given to the underlying call to the grep(3) command, the default options may also be defined with the find-setup(3) command invoked from the command line or from the the Tools menu. The find-options are defined as follows:

--


Last option, the following string must be the first file-mask which may start with a '-'.

-a


Re-read all out of date buffers, prevents a manual prompt, equivalent of Yes to all. This is the inverse of -o

-b


Ignore binary files.

-B


Do not ignore binary files (not advisable as this is a text based search and replace operation).

-c


Command return the number of matchs found/replaced rather than the default, which is simply 0 for one or more matches or 1 if no matches were found/replaced.

-C


Command returns 0 (non-error for command-line tool) regardless of if it finds any matches.

-g


File masks are regex (i.e. .*.emf)

-G


File masks are not regex (i.e. *.emf)

-i


Ignore search pattern case (case insensitive).

-I


Do not ignore search pattern case (case sensitive).

-l


Use existing buffer of loaded files.

-L


Do not use existing buffer of loaded files.

-m


Search pattern is a regular expression.

-M


Search pattern is not a regular expression.

-o


Do not re-read all out of date buffers, prevents a manual prompt, equivalent of No to all. This is the inverse of -a.

-p


Starting path specified

-P


Starting path not specified

-q


Enables quiet mode for reduced print-out.

-r


Recurse into sub-directories

-R


Do not recurse into sub-directories

-S <size>


File size - less than or equal, the following size formats are supported:

-S <number> File size specified bytes.

-S <number>k File size specified in Kilobytes.

-s <size>


File size greater than; supported size formats are the same as -S.

-T <time>


Modification time - older than, the following time formats are supported:

-T yy-mm-dd

-T yyyy-mm-dd

-T yyyy-mm-dd hh:mm:ss

-T days Offset time in days from midnight this morning, e.g. -T 0 would match all files not modified today.

-T days.hours[.minutes[.seconds]] Offset time in , e.g. -T 1.1.30 matches all files 25 hours and 30 minutes old.

Note that -T 1 is not the same as -T 1.0, except at midnight.

-t <time>


Modification time - newer than or equal, supported time formats are the same as -T.

-u


When used with -w, allows the file size limit of 100MB to be disabled and strings are searched in files of any size.

-U


When used with -U, files are limited in size 100MB otherwise they will not be searched.

-w <search-pattern>


File must contain a string matching the given search-pattern.

-W <search-pattern>


File must not contain a string matching the given search-pattern.

-x


Use MicroEmacs $file-ignore(5) to exclude unimportant files

-X


Do not use MicroEmacs $file-ignore(5).

-&


Launch command using a separate process, this stops the current MicroEmacs hanging during the replace process which can be useful for time consuming searches, not supported by query-replace-string-in-files.

file-mask


The files to search for e.g. *.txt

starting-path


Specifies the directory location where the search should commence when the -p option is used, the default when -p is omitted is the location of the current buffer.

NOTES

• The location of the find options in the 3rd argument may seem odd, but the command is not required to have a single <options> <from> <to> <mask> interface as this becomes unwieldy.
• The default when no options are given is -XGPRDfMIbL, default options may be set via the find-setup(3) command (sets /history/rsif-com registry entry).
• The -d option is not supported as find(3) and error is reported if supplied.
• It may be advantageous to enable the -l option default using find-setup(3).
• Use of -w is supported and is separate from the <from-pattern>, i.e. this option can still be used to filter the files to operate on.
• -w shares the -m and -i options, i.e if -m is used both the <from-pattern> and the <search-pattern> must be a regular expression pattern.

The other options of the underlying find(3) command are allowed but provide no benefit to these commands.

SEE ALSO

find(1), grep(1), find(3), grep(3), find-setup(3), get-next-line(2), grep(1), xfind(3), xgrep(3), rgrep(3).

Ref: replace-string-in-files(3) File: m3mac090.3 Date: 2025/03/16

(c) Copyright JASSPA 2026