About
git-search-replace is a small utility on top of plain git for performing project-wide search-and-replace only on git-controlled files. It applies its searches to filenames as well as their content. The underlying syntax for the search regex is Python's.
It is designed to be a bit more instructive to the developer, compared to hackish bash scripts around sed.
An accompanying utility is gsr-branch, which does the same thing as git-search-replace but on the history of a branch (using git filter-branch). It's especially useful for fixing a whole bunch of commits at once when the fix is a simple search & replace (retaining a clean history).
Key features are:
- By default, only act as grep to show what is going to change.
- Dry run mode (
--diff) shows a unidiff of the changes that the search-and-replace would do, so that the developer can review for correctness. No working directory files are modified. - Fix mode (
--fix) performs the actual changes and associated 'git mv'.
Wait, but my awesome editor can already do that!
That's right, but when you are working within a group of people and everyone has their own editor, it becomes quite useful to be able to communicate renames in a way that everyone can easily reproduce, and during conflict resolution it is even more useful (see: git-mediate). This comes handy especially in commit message, for instance:
commit 3ed68e243e76783fa2b92fa33f7e4681f0246332
Author: Dan Aloni <[email protected]>
Date: Sun Jul 26 18:42:52 2015 +0300
module: renamed with: gsr foo///bar -f
Syntax
Usage: gsr [options] (FROM-SEPARATOR-TO...)
gsr [options] -p FROM1 TO1 FROM2 TO2 ...
Options:
-h, --help show this help message and exit
-s STRING, --separator=STRING
The separator string the separates FROM and TO
regexes. /// by default, if -p is not specified
-p, --pair-arguments Use argument pairs for FROM and TO regexes. Useful with
shell expansion. E.g: colo{,u}r
-f, --fix Perform changes in-place
-d, --diff Use 'diff' util to show differences
-e PATTERN, --exclude=PATTERN
Exclude files matching the provided globbing pattern
(can be specified more than once)
-i PATTERN, --include=PATTERN
Include files matching the provided globbing pattern
(can be specified more than once)
--no-renames Don't perform renames
The expressions are tuples in the form of FROM-SEPARATOR-TO, with SEPARATOR defaults to '///'.
The -e and -i options abide by the following rules:
- Each of these can be passed multiple times.
- The order matters, as they are checked in that order for each file. Last matcher takes effect when matched.
- If neither is passed, all files are included by default.
- If
-iif given first, then by default all files are excluded.
Examples
Shell escaping needs to be taken into consideration. The examples below should work with the major UNIX shells.
gsr old_name///new_name --diff
This shows a diff that represents the replacement of 'old_name' with 'new_name'.
gsr \\bold_name\\b///new_name --fix
This uses Python regex expression \b for matching at word boundaries for whole identifiers. This invocation will perform changes in-place because of '--fix'.
gsr 'things with space///with other stuff' --diff
Note that shells properly de-escape the quotes from the expression above.
Example of using gsr-branch:
gsr-branch.py HEAD~10 '(\.|\-\>)ol_header///\1header'
Runs the search replace regex over the last 10 commits, modifying them in-place. The regex will replace the string .ol_header (or ->ol_header) with .header (or ->header).