sr — safe, auditable search & replace for source trees#

sr rewrites text across a whole tree of files and keeps a journal of every
change, so any run can be inspected, diffed and undone.

It is built for the jobs where sed -i is too blunt and an editor's
project-wide replace is too manual: retiring an API, bumping versions in a dozen
manifests, migrating a config key, normalising encodings, bulk-renaming files.

$ sr find "old_api" -p '*.py'            # where is it?
src/app.py:12:5: result = old_api.call()
src/util.py:3:1: import old_api
2 matches in 2 files (scanned 128) in 41ms

$ sr diff "old_api" "new_api" -p '*.py'  # what exactly would change?
--- a/src/app.py
+++ b/src/app.py
@@ -12 +12 @@
-result = old_api.call()
+result = new_api.call()

$ sr replace "old_api" "new_api" -p '*.py'
[ok] src/app.py: 1 replacement(s)
[ok] src/util.py: 1 replacement(s)
Session                20260131T120530Z-9f3a1c
Rollback               sr rollback 9f3a1c

$ sr rollback                            # changed your mind?
[ok] session 9f3a1c rolled back (2 files)

Contents#

• Why sr

• Install

• Quick start

• Commands

• Matching

• Choosing files

• Sessions, backups and rollback

• Automation: JSON, porcelain, exit codes

• Configuration

• Self-update

• Shell completion and man page

• Option reference

• Safety model

• Performance

• Troubleshooting

• Architecture

• Development

• Migrating from sr 6.x

• License

Why sr#

Most search-and-replace tools are thin wrappers around grep + sed. That
design has four consequences that show up exactly when the edit is large enough
to matter:

Plus the things that make it usable in a pipeline: stable documented exit codes,
--json, --porcelain, --yes, an advisory lock so two runs cannot
interleave, encoding/BOM/line-ending preservation, and no third-party runtime
dependencies at all.

Install#

sr is a single-file Python application. Python 3.10 or newer is the only
requirement — no packages to install, no compilation, no service. Tested on
3.10 through 3.14; see Platforms for the OS story.

Standalone (recommended)#

curl -fsSL https://raw.githubusercontent.com/paulmann/sr-search-replace/main/scripts/install.sh | bash

The installer resolves the newest release, downloads sr.pyz and sr.pyz.sha256,
verifies the checksum, smoke-tests the download and installs it to
/usr/local/bin/sr (override with --prefix ~/.local/bin). A failed
verification installs nothing.

curl -fsSLO https://github.com/paulmann/sr-search-replace/releases/latest/download/sr.pyz
curl -fsSLO https://github.com/paulmann/sr-search-replace/releases/latest/download/sr.pyz.sha256
sha256sum -c sr.pyz.sha256          # must print OK
install -m 0755 sr.pyz /usr/local/bin/sr

pipx / pip#

pipx install sr-search-replace       # isolated, recommended
python3 -m pip install --user sr-search-replace

npm#

npm install -g sr-search-replace

The npm package bundles the same zipapp; the launcher finds python3 and
reports a precise error if it is missing or too old.

From source#

git clone https://github.com/paulmann/sr-search-replace
cd sr-search-replace
make test          # the full suite (~730 tests), no network
make install       # zipapp + man page into PREFIX (default /usr/local)

Verify any installation#

sr --version       # version, interpreter, installation type
sr doctor          # environment, filesystem capabilities, config, session store
sr selftest        # end-to-end smoke test in a temporary directory

Platforms. Officially Linux and macOS. On Windows use WSL2.

The Python entry point does import and run on native win32, and sr find /
--dry-run will work, but the write path is not supported there and is not
tested in CI: sr relies on POSIX rename semantics, os.chown, O_CREAT|O_EXCL
advisory locks, inode preservation and os.statvfs. The npm launcher refuses on
win32 for exactly that reason, and pyproject.toml carries no Windows
classifier. sr doctor reports which of those capabilities the current
filesystem actually provides.

Quick start#

# 1. look
sr find "TODO" -p '*.py'
sr diff "old" "new" -p '*.py'

# 2. do (creates a rollback session automatically)
sr replace "old" "new" -p '*.py'

# 3. review, and undo if needed
git diff                 # or: sr diff --session latest
sr rollback              # restores every file of the last session

A bare invocation is a shortcut for replace, and flags work in any position:

sr "*.py" "old" "new"            ==  sr replace "*.py" "old" "new"
sr "old" "new" -p '*.py' -i      ==  sr replace -i -p '*.py' "old" "new"

Quote your globs. sr replace *.py a b lets the shell expand *.py;
sr replace '*.py' a b lets sr walk the tree. Both work, but only the
second one recurses.

The built-in manual#

sr help is a real manual — 27 topics, generated from the same schema that
drives the parser, so it cannot drift out of date.

sr help                    # overview and quick start
sr help topics             # the topic index
sr help matching           # literal vs --regex/--ere/--pcre, ranges, counts
sr help rollback           # drift detection, undoing a rollback
sr help replace            # everything one command accepts
sr help --max-count        # one option in depth, with an example
sr help examples           # ~40 ready-to-run command lines
sr help --all              # the whole manual in one document
sr help --json             # the same content, machine readable
man sr                     # the same content as a man page

Commands#

Every command accepts -h/--help.

replace#

sr replace "old_api" "new_api" -p '*.py' -p '*.pyx'
sr replace 'version = "(\d+)"' 'version = "\1.post0"' --regex -p setup.py
sr replace "Warning" "Notice" -i -w -p '*.md'
sr replace "old" "new" --dry-run                     # count only, write nothing
sr replace "old" "new" --interactive                 # confirm every hunk
sr replace "old" "new" --write=dir -o out            # copies; originals untouched
sr replace "old" "new" --write=stdout | less         # pipe the result
sr replace "old" "new" --line-range 1-20 -p 'header*'
sr replace "old" "new" --max-count 1
sr replace "old" "new" --encoding cp1251 -p '*.txt'
sr replace "MyClass" "YourClass" --rename -p '*.py'  # content *and* file names

find#

sr find "deprecated" -p '*.py'            # file:line:col + the line, highlighted
sr find "deprecated" --count              # per-file counts and a total
sr find "deprecated" -l                   # file names only
sr find "deprecated" -A 2 -B 2            # with context
sr find 'v\d+\.\d+' --regex --porcelain | cut -d: -f1 | sort -u

rename#

sr rename ".txt" ".md" -p '*.txt'
sr rename --regex '^photo-(\d+)\.jpeg$' 'img_\1.jpg'
sr rename "old" "new" --dry-run           # the plan, without executing it

Renames never move a file to another directory, collisions are detected before
anything is executed, and the whole thing is journalled so sr rollback undoes
it in reverse order.

doctor, selftest, config, completions#

sr doctor --json | jq '.checks[] | select(.status != "ok")'
sr selftest                                # 19 end-to-end checks in ~50 ms
sr config list --show-origin               # every option and where it came from
sr config init                             # documented template in ~/.config/sr/
sr completions --install                   # bash/zsh/fish, auto-detected

Matching#

Four pattern kinds. Literal is the default, which is the single most
important difference from sed:

sr replace "1.2.3" "1.2.4"            # a dot is a dot
sr replace '1\.2\.3' '1.2.4' --regex  # now it is a regex

Modifiers, applied uniformly to every kind:

Escape sequences recognised in fixed patterns: \n \t \r \f \0 \e \\ \' \" \xNN.
\b is deliberately not one of them — C:\bin must stay C:\bin, not
become a backspace. Unknown escapes keep their backslash.

Counting rule: occurrences, not lines. A line with three hits counts three,
in find, in the confirmation prompt, in --max-count and in the summary —
because all of them ask the same matcher.

$ sr help matching        # the full chapter, with a cheat sheet

Choosing files#

sr replace a b -p '*.py'                     # by name (repeatable)
sr replace a b --include 'src/**/*.py'       # by path, ** supported
sr replace a b --exclude '*.min.js' --exclude 'vendor/*'
sr replace a b --file src/app.py --file src/main.py
git ls-files '*.py' | sr replace a b --files-from -
sr replace a b -C ~/projects/api             # another directory
sr replace a b --no-recursive --max-depth 2
sr replace a b --hidden -p '.env*'
sr replace a b --gitignore                   # honour .gitignore
sr replace a b --max-size 1MB --newer-than 7d

Safe by default: .git, .hg, .svn, node_modules, vendor, dist,
build, target, __pycache__, .venv, .cache, .gradle, .terraform,
.idea, .vscode are pruned before descending (so scanning them costs
nothing); .DS_Store, *.orig, *.rej, *.bak, *.swp, *~ are skipped;
hidden files are skipped; symlinks are skipped; binary files are skipped; and
sr's own .sr/ store is always pruned so a rollback can never feed on itself.

Add -v to see why a candidate was skipped — every rejection has a reason:

$ sr find "x" -v
[verbose] skipped assets/logo.png: binary content (use --binary to force)
[verbose] skipped vendor/lib.js: excluded directory (vendor)
[verbose] skipped dist/app.js: ignored by .gitignore

Sessions, backups and rollback#

Every mutating run writes a session:

<target>/.sr/sessions/20260131T120530Z-9f3a1c/
├── manifest.json    who, what, when; per-file SHA-256, size, mode, uid/gid
├── journal.jsonl    append-only op log, fsync-ed per file (crash-safe)
├── files/9f/9f3a….dat   the original bytes, content addressed
└── diffs/src/app.py.diff

• Content addressed — identical originals are stored once, so 10 000 files
  sharing a header cost one blob. Every blob is re-hashed on read: a truncated
  or tampered backup is reported, never silently restored.

• Journal first, manifest last — a run killed halfway still has a usable
  journal, and sr rebuilds enough of the session from it to roll back.

• Add .sr/ to .gitignore. Use --backup-dir to keep sessions outside
  the tree (read-only checkout, or you simply do not want the directory).

• --no-backup skips the store entirely — the right choice inside a clean
  git working tree, where git checkout -- . is your rollback.

Rolling back#

sr sessions                     # what can I undo?
sr rollback                     # newest session
sr rollback 9f3a1c              # by unique id suffix
sr rollback 2                   # ordinal: 2 = the second newest
sr rollback latest --dry-run    # show what would be restored
sr rollback latest --file src/app.py
sr diff --session latest        # the diffs that run recorded

Drift detection. The manifest stores the SHA-256 of each file after the
run. Before restoring, sr hashes the file as it is now:

That is what makes sr rollback safe to run hours later: it will not throw away
edits you made in the meantime.

The rollback is itself reversible. Unless you pass --no-safety-snapshot,
the pre-rollback state is recorded in a new session of kind rollback:

$ sr rollback --yes
[ok] session 9f3a1c rolled back (2 files)
Undo this rollback     sr rollback 20260131T120918Z-4b7e21

Retention. --keep N (default 20) and --keep-age 30d are applied after
every mutating run, so the store cannot grow without bound:

sr sessions size
sr sessions prune --keep 10 --keep-age 30d

Automation: JSON, porcelain, exit codes#

--json#

One document on stdout; every diagnostic goes to stderr, so
sr … --json | jq is always safe.

sr replace "$OLD" "$NEW" --yes --json --no-update-check > report.json
jq -e '.totals.failed == 0' report.json
jq -r '.files[] | select(.status=="changed") | "\(.rel_path): \(.replacements)"' report.json

{
  "version": "7.0.0",
  "dry_run": false,
  "root": "/home/me/project",
  "search": "old", "replacement": "new", "pattern_kind": "fixed",
  "duration_seconds": 0.412,
  "totals": {
    "scanned": 128, "changed": 7, "unchanged": 121, "skipped": 2,
    "failed": 0, "matches": 19, "replacements": 19, "renamed": 0,
    "bytes_read": 421887, "bytes_written": 20144
  },
  "session": { "id": "20260131T120530Z-9f3a1c", "…": "…" },
  "files": [
    { "path": "…", "rel_path": "src/app.py", "status": "changed",
      "matches": 3, "replacements": 3, "encoding": "utf-8",
      "size_before": 4012, "size_after": 4015,
      "diff": { "added": 3, "removed": 3, "changed": 6 } }
  ],
  "errors": [], "warnings": [], "exit_code": 0
}

Add --diff to include each file's patch text as "patch".

--porcelain#

Stable path:line:col:kind:text records, designed to be cut and piped:

sr find "TODO" --porcelain | cut -d: -f1 | sort -u

Exit codes#

Full table, per-command behaviour and the reasoning behind the split:
docs/EXIT_CODES.md (generated from sr/exit_codes.py)
or sr help exit-codes.

if sr replace "$OLD" "$NEW" --yes -q; then
  echo changed
elif [ $? -eq 3 ]; then
  echo "nothing to do"
else
  echo failed >&2; exit 1
fi

CI checklist#

• --yes — never prompt (sr refuses to prompt when stdin is not a terminal and
  exits non-zero instead of hanging the job)

• --no-update-check — keep the network out of the job

• --json or --porcelain — parse, do not scrape

• --no-backup when the workspace is a fresh checkout, or --backup-dir
  pointed at a cache directory when you want the rollback

• SR_NO_COLOR=1 / --color never — no ANSI codes in the log

• sr selftest as a post-install step in the image

Configuration#

Precedence, lowest to highest:

built-in defaults
  → /etc/sr/sr.conf
  → $XDG_CONFIG_HOME/sr/sr.conf          (~/.config/sr/sr.conf)
  → <project root>/.srrc , <target>/.srrc , <target>/.sr/sr.conf
  → $SR_CONFIG  /  --config-file FILE
  → SR_* environment variables
  → --config KEY=VALUE
  → command line flags

A small, forgiving INI dialect:

# ~/.config/sr/sr.conf
ignore-case = true              # applies to every command
exclude = *.min.js, dist        # comma or whitespace separated

[replace]                       # `sr replace` only
confirm-threshold = 500
keep = 50

[find]
context = 1

Rules: keys are option names (- and _ interchangeable) · a bare key means
true · booleans accept true/false/yes/no/on/off/1/0 · sizes accept 512,
4KB, 10MB, 1.5GiB · durations accept 30s, 5m, 7d · repeating a key
builds a list · an unknown key or an invalid value is a hard error with
file:line, because a silently ignored typo is exactly what a bulk-edit tool
must not have.

sr config list --show-origin     # every option, its value, where it came from
sr config show confirm-threshold
sr config init                   # documented template
sr config path                   # the files sr reads, in priority order
sr config validate               # parse them all, report errors

Every option also has an SR_* environment variable — the option name in upper
case with - → _:

SR_IGNORE_CASE=true sr replace "warning" "notice" -p '*.md'
export SR_EXCLUDE='*.min.js vendor/*'

A project .srrc is worth committing: it turns the team's exclusion list,
confirmation threshold and backup policy into repository content instead of
tribal knowledge.

Self-update#

sr update --check              # is there a newer release?
sr update                      # install it
sr update --version 7.1.0      # pin a specific version
sr update --channel prerelease
sr update --source npm         # ask the npm registry instead of GitHub

sr doctor reports the installation type, which decides how an update is
applied:

Every step either succeeds or leaves the current installation untouched — a
checksum mismatch or a failing smoke test installs nothing.

Background check. At most once per 24 h, sr looks for a newer release on a
daemon thread with a 2.5 s budget and caches the answer under
$XDG_CACHE_HOME/sr/update-check.json. It never blocks a run: on a slow or
absent network nothing is printed and the cache is used next time. Disable it
with --no-update-check or SR_NO_UPDATE_CHECK=1 — a good idea in CI and on
air-gapped machines.

sr update --version 7.0.0 && export SR_NO_UPDATE_CHECK=1     # pin
SR_GITHUB_TOKEN=… sr update --check                          # higher API limit

Shell completion and man page#

sr completions --install                 # auto-detects bash / zsh / fish
sr completions bash >> ~/.bash_completion
sr completions zsh  > "${fpath[1]}/_sr"
sr completions fish > ~/.config/fish/completions/sr.fish
man sr

Both are generated from the live option schema (make completions,
make man), so a new flag appears in the parser, the config layer, the help
system, the completions and the man page from one declaration — and CI fails if
a committed artefact drifts out of date.

sr help pages its output through $PAGER on a terminal; --no-pager
disables that. sr … | head exits 0 rather than dumping a BrokenPipeError.

Option reference#

61 tunables. Every one is also a config-file key and an SR_* variable.
sr help options prints this table with examples; sr help --<flag> explains
one option in depth.

60 cross-command options. Each one is also a configuration key (see sr config list) and an SR_* environment variable.

These are declared next to their subparser rather than in the shared
schema, because they exist for exactly one command. They are generated
into this table from the live parser, so they cannot go stale.

Global

sr replace

sr find

sr diff

sr rename

sr rollback

sr sessions

sr update

sr doctor

sr completions

sr config

sr selftest

sr help

Global flags: -h/--help, --help-all, -V/--version, -v/--verbose (-vv
= debug), -q/--quiet, --debug, --json, --porcelain, --color auto|always|never, --no-update-check, --config KEY=VALUE, --config-file FILE.

Safety model#

Threat model: sr runs with your privileges over your files, so the risks are
accidental destruction, unintended scope and supply-chain attacks on
the update path — not remote exploitation.

Accidental destruction

• literal matching by default: a pattern is never silently a regex

• binary files are skipped unless --binary or an explicit --encoding is given

• undecodable files are skipped and reported — never rewritten with a guessed
  encoding (BOM, UTF-8, --encoding, then --encoding-error)

• the scan phase completes before the first write, so the confirmation prompt
  states real numbers (--confirm-threshold, default 50 files)

• VCS directories, build output and .sr/ are pruned by default

• symlinks are skipped by default, so a link cannot smuggle a file outside the
  target tree into the edit set

• atomic writes by default (--atomic): a crash can never leave a truncated
  file; --no-atomic preserves the inode instead, for hard links

• running as root is refused unless --allow-root

• rewriting /, /etc, /usr or $HOME directly is refused unless
  --force

• every mutating run is journalled and reversible; rollbacks are reversible too

• rollback refuses drifted files, refuses paths outside the session root, and
  re-hashes every blob before writing it

Unintended scope

• -v prints every skipped candidate with the reason

• --dry-run and --diff make the blast radius visible before committing

• --write=dir -o out produces copies and touches nothing

Update path (supply chain)

• HTTPS only, enforced in code (_require_https rejects file: and custom
  schemes before urlopen sees them)

• verification is fail-closed: a missing checksum asset, an unreachable or
  empty checksum file, a malformed digest and a digest mismatch all abort the
  update and install nothing — scripts/install.sh enforces the same five rules

• the download is smoke-tested in a subprocess before it replaces anything

• the previous file is kept as <file>.bak

• --no-verify is the only way past that, and warns loudly

• the background check is read-only, cached, non-blocking and can be disabled

Data handling

• file content never leaves the machine; the only network calls are the release
  lookup and the release download

• sessions store original bytes under <target>/.sr — not encrypted; treat
  that directory with the same care as the files themselves and keep it out of
  git

• no telemetry, no analytics, no crash reporting: a crash prints a traceback
  locally (with SR_DEBUG=1) and suggests opening an issue

See SECURITY.md for reporting a vulnerability.

Performance#

Where the time goes, in order of impact: discovery (pruning is the whole
game — excluded directories are never descended into), reading and decoding
(every candidate is read once), matching (one compiled pattern reused for
every file), writing (one atomic write plus an fsync per changed file).

On a laptop SSD a literal replacement across ~10 000 text files (≈120 MB) takes
a few seconds. The scan phase doubles the read cost of a mutating run — that is
the price of an accurate prompt and of a --dry-run with no side effects.

sr replace a b --files-from <(git ls-files '*.py')   # skip discovery entirely
sr replace a b --no-backup                           # no blob writes (git is your net)
sr replace a b -q --no-progress --no-summary         # script-friendly
sr replace a b --max-size 1MB --newer-than 7d        # shrink the candidate set

No parallelism by default, deliberately. A bulk rewrite is I/O bound, and
parallel writers make the journal order — and therefore rollback — harder to
reason about. If you need throughput, shard by directory with -C and run the
shards yourself: each shard gets its own session and can be rolled back
independently.

Troubleshooting#

Start with sr doctor (interpreter, installation type and writability, config
files, session store, filesystem capabilities, locking, disk, network) and
sr selftest (the whole pipeline end to end).

sr help troubleshooting      # the full chapter

Architecture#

sr-cli, sr.py             launchers (POSIX sh / thin Python)
sr/
  cli.py                  preprocessing, dispatch, error handling
  cli_support.py          argparse actions, schema → parser plumbing
  registry.py             the subcommand table
  options.py              THE option schema (single source of truth)
  config.py               config files, env vars, precedence
  context.py              per-run context: console, config, prompts, guards
  console.py              colour, verbosity, text/json/porcelain output
  pattern.py              the matcher: literal/regex/ERE/PCRE, ranges, counts
  discovery.py            walking, pruning, globs, .gitignore, filters
  textio.py               encoding, BOM, line endings, binary sniffing
  replace.py              the engine: scan → confirm → write → record
  find.py                 read-only search rendering (grep-like output)
  diffview.py             unified diffs and their statistics
  atomic.py               atomic, permission-preserving writes
  session.py              sessions: manifest, journal, blob store, restore
  errors.py               exception hierarchy → exit codes
  exit_codes.py           the frozen exit-code contract
  util.py, version.py     sizes, durations, hashes, ids, semver
  help_system.py          the manual: 27 topics, generated option reference
  commands/               one module per subcommand (+ shared helpers)
tools/                    build helpers: zipapp, man page
scripts/                  install.sh, version sync, release notes
tests/                    ~590 test functions → ~730 tests; hermetic (no network, no $HOME)
npm/                      the npm package (launcher + bundled zipapp)

Data flow of sr replace:

argv → preprocess → argparse → Context (config merge, console)
     → PatternSpec (validated once)
     → DiscoveryOptions → discover() → candidate list
     → SCAN:   read → decode → match → diff            (nothing written)
     → confirm (accurate numbers)
     → WRITE:  atomic write → session.record_replace()
     → close session (manifest) → prune → report → exit code

Invariants worth knowing:

• the scan phase never writes, so --dry-run has literally no side effects

• counting and replacing share one matcher, so the reported number of
  replacements equals the number of edits made

• the journal is fsync-ed per file and the manifest only at the end, so an
  interrupted run is still recoverable

• blobs are content addressed and re-hashed on read: a corrupt backup is
  detected, never silently restored

• a session may never cause a write outside its own root, even if the manifest
  is edited by hand

Development#

git clone https://github.com/paulmann/sr-search-replace
cd sr-search-replace
python3 -m venv .venv && . .venv/bin/activate
make install-dev        # editable install + pytest/ruff/mypy
make test               # the full suite
make lint               # ruff
make dist               # build/sr.pyz (the release asset)
make man completions    # regenerate the derived artefacts
make check              # lint + types + tests + dist + man + versions + selftest

Conventions (all enforced by review or CI):

• a new option goes into sr/options.py and nowhere else — the parser,
  config layer, help text, man page and completions are all derived from it

• every command module exposes cmd_<name>(context) -> int

• errors are SrError subclasses carrying an exit code and a one-line hint

• no third-party runtime dependencies, ever

• tests must not touch the network, the real $HOME, or the cwd

Release checklist: bump version in pyproject.toml → make sync-version V=x.y.z
→ update CHANGELOG.md → make release-check → commit, tag vx.y.z, push.
CI publishes to PyPI and npm, builds sr.pyz, and attaches sr.pyz +
sr.pyz.sha256 to the GitHub Release — which is exactly what sr update downloads
and verifies.

See CONTRIBUTING.md.

Migrating from sr 6.x#

sr 7 is a rewrite in Python with a redesigned command line. The 6.x flags are
not accepted.

Behaviour changes worth knowing

• Patterns are literal by default. 6.x escaped the search string for sed,
  which also meant -E was effectively broken; 7.x separates literal and regex
  cleanly.

• Replacement counts are occurrences, not matching lines.

• --dry-run writes nothing at all (6.x created a backup directory).

• Sessions live in .sr/ instead of sr.backup.<timestamp>/ in the project
  root. 6.x backup directories are left untouched — restore from them with the
  6.x script from the v6.1.0 release assets, or copy the files back by hand
  (the layout is a plain directory mirror).

• Exit codes are documented and stable: "no match" is 3, not 1.

• 6.x required bc, file, GNU sed/grep and bash 4 at runtime and failed
  with exit 127 when any of them was missing. 7.x needs Python 3.10+ and
  nothing else.

sr help compat        # the same table, plus the reasoning

License#

PolyForm Noncommercial 1.0.0 © Mikhail Deynekin — deynekin.com

sr help license