# sr — option reference

This page is **generated** from the option schema in `sr/options.py` by
`scripts/gen_options_table.py`.  Do not edit it by hand: change the schema and
run `make docs`.

The same content is available offline and always in sync with the binary you
have installed:

```sh
sr help options            # every option, grouped, with defaults and env vars
sr help --max-count        # one option in depth, with an example
sr help matching           # the prose chapter about pattern kinds
sr <command> --help        # everything one command accepts
man sr                     # the same, as a man page
```

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
```

<!-- BEGIN OPTIONS — generated by scripts/gen_options_table.py; do not edit -->

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

<details open>
<summary><b>Target selection</b> (18)</summary>

| Flag | Environment | Default | What it does |
| --- | --- | --- | --- |
| `-C`, `--target` `DIR` | `SR_TARGET` | `.` | Directory to operate on (default: the current directory). *(`replace`, `find`, `diff`, `rename`)* |
| `-p`, `--pattern` `GLOB` | `SR_PATTERN` | — | Only files whose name matches GLOB (repeatable). Default: every text file. *(`replace`, `find`, `diff`, `rename`)* |
| `--file` `PATH` | `SR_FILE` | — | Explicit file to process, bypassing pattern matching (repeatable). *(`replace`, `find`, `diff`, `rename`)* |
| `--files-from` `FILE` | `SR_FILES_FROM` | — | Read the list of target files from FILE, one per line ('-' for stdin). *(`replace`, `find`, `diff`, `rename`)* |
| `--include` `GLOB` | `SR_INCLUDE` | — | Additional include glob, may contain '/' and '**' (repeatable). *(`replace`, `find`, `diff`, `rename`)* |
| `--exclude` `GLOB` | `SR_EXCLUDE` | — | Exclude glob; wins over --include and --pattern (repeatable). *(`replace`, `find`, `diff`, `rename`)* |
| `--exclude-dir` `NAME` | `SR_EXCLUDE_DIR` | — | Prune a directory by name (repeatable; adds to the built-in list). *(`replace`, `find`, `diff`, `rename`)* |
| `--no-default-excludes` | `SR_NO_DEFAULT_EXCLUDES` | — | Do not apply the built-in exclude lists (node_modules, dist, *.bak …). *(`replace`, `find`, `diff`, `rename`)* |
| `-1`, `--no-recursive` | `SR_NO_RECURSIVE` | — | Only the target directory itself, no subdirectories. *(`replace`, `find`, `diff`, `rename`)* |
| `--max-depth` `N` | `SR_MAX_DEPTH` | — | Descend at most N levels below the target directory. *(`replace`, `find`, `diff`, `rename`)* |
| `--hidden` | `SR_HIDDEN` | — | Also process dotfiles and dot-directories. *(`replace`, `find`, `diff`, `rename`)* |
| `--symlinks` | `SR_SYMLINKS` | — | Follow symlinked files (they are skipped by default). *(`replace`, `find`, `diff`, `rename`)* |
| `--gitignore` | `SR_GITIGNORE` | — | Honour .gitignore files (including the global excludesfile). *(`replace`, `find`, `diff`, `rename`)* |
| `--max-size` `SIZE` | `SR_MAX_SIZE` | `100.0 MB` | Skip files larger than SIZE (default 100MB; a bare number means megabytes). *(`replace`, `find`, `diff`, `rename`)* |
| `--min-size` `SIZE` | `SR_MIN_SIZE` | — | Skip files smaller than SIZE. *(`replace`, `find`, `diff`, `rename`)* |
| `--newer-than` `AGE` | `SR_NEWER_THAN` | — | Only files modified within AGE (e.g. 24h, 7d, 30m). *(`replace`, `find`, `diff`, `rename`)* |
| `--older-than` `AGE` | `SR_OLDER_THAN` | — | Only files not modified within AGE. *(`replace`, `find`, `diff`, `rename`)* |
| `--binary` | `SR_BINARY` | — | Process files that look binary instead of skipping them. *(`replace`, `find`, `diff`, `rename`)* |

</details>

<details open>
<summary><b>Matching</b> (12)</summary>

| Flag | Environment | Default | What it does |
| --- | --- | --- | --- |
| `-R`, `--regex` | `SR_REGEX` | — | Treat PATTERN as a Python regular expression. *(`replace`, `find`, `diff`, `rename`)* |
| `--ere` | `SR_ERE` | — | Treat PATTERN as a POSIX Extended Regular Expression (grep -E syntax). *(`replace`, `find`, `diff`, `rename`)* |
| `--pcre` | `SR_PCRE` | — | Treat PATTERN as a Perl-compatible regular expression. *(`replace`, `find`, `diff`, `rename`)* |
| `--pattern-kind` `KIND` | `SR_PATTERN_KIND` | `fixed` | Explicit pattern kind: fixed, regex, ere or pcre — one of `fixed`, `regex`, `ere`, `pcre`. *(`replace`, `find`, `diff`, `rename`)* |
| `-i`, `--ignore-case` | `SR_IGNORE_CASE` | — | Case-insensitive matching. *(`replace`, `find`, `diff`, `rename`)* |
| `-w`, `--word-boundary` | `SR_WORD_BOUNDARY` | — | Match whole words only. *(`replace`, `find`, `diff`, `rename`)* |
| `-m`, `--multiline` | `SR_MULTILINE` | — | Allow the pattern to span line boundaries ('.' matches newline). *(`replace`, `find`, `diff`, `rename`)* |
| `--no-escapes` | `SR_NO_ESCAPES` | — | Do not interpret \n, \t, \xNN in fixed patterns/replacements. *(`replace`, `find`, `diff`, `rename`)* |
| `-L`, `--line-range` `RANGE` | `SR_LINE_RANGE` | — | Restrict edits to a line range: 10, 10-20, 10- or -20. *(`replace`, `find`, `diff`, `rename`)* |
| `-M`, `--max-count` `N` | `SR_MAX_COUNT` | — | Replace at most N occurrences per file. *(`replace`, `find`, `diff`, `rename`)* |
| `--no-global` | `SR_NO_GLOBAL` | — | Replace only the first occurrence on each line. *(`replace`, `find`, `diff`, `rename`)* |
| `--context` `N` | `SR_CONTEXT` | `3` | Lines of context around a match in preview/diff output (default 3). *(`replace`, `find`, `diff`, `rename`)* |

</details>

<details open>
<summary><b>Action</b> (13)</summary>

| Flag | Environment | Default | What it does |
| --- | --- | --- | --- |
| `-n`, `--dry-run` | `SR_DRY_RUN` | — | Report what would change; never write, never create a session. *(`replace`, `find`, `diff`, `rename`)* |
| `--diff` | `SR_DIFF` | — | Show a unified diff of every change (implies a preview). *(`replace`, `find`, `diff`, `rename`)* |
| `-I`, `--interactive` | `SR_INTERACTIVE` | — | Confirm every hunk before it is written. *(`replace`, `find`, `diff`, `rename`)* |
| `--write` `MODE` | `SR_WRITE` | `in-place` | Where the result goes: in-place (default), stdout, or --output-dir — one of `in-place`, `stdout`, `dir`. *(`replace`)* |
| `-o`, `--output-dir` `DIR` | `SR_OUTPUT_DIR` | — | Write modified copies under DIR, mirroring the tree (needs --write=dir). *(`replace`)* |
| `--suffix` `EXT` | `SR_SUFFIX` | — | When writing copies, append EXT to the file name instead of mirroring. *(`replace`)* |
| `--rename` | `SR_RENAME` | — | Also apply the replacement to file and directory names. *(`replace`)* |
| `--rename-only` | `SR_RENAME_ONLY` | — | Rename matching files/directories without touching their content. *(`replace`)* |
| `-E`, `--encoding` `NAME` | `SR_ENCODING` | — | Force an encoding (utf-8, cp1251, latin-1 …); default is auto-detect. *(`replace`, `find`, `diff`, `rename`)* |
| `--encoding-error` `POLICY` | `SR_ENCODING_ERROR` | `strict` | What to do with undecodable bytes: strict (skip), replace, ignore — one of `strict`, `replace`, `ignore`. *(`replace`, `find`, `diff`, `rename`)* |
| `--line-endings` `MODE` | `SR_LINE_ENDINGS` | `preserve` | Keep the file's line endings (default) or normalise to LF/CRLF — one of `preserve`, `lf`, `crlf`. *(`replace`)* |
| `--preserve-mtime` | `SR_PRESERVE_MTIME` | — | Restore the original modification time after writing. *(`replace`)* |
| `-y`, `--yes` | `SR_YES` | — | Answer 'yes' to every prompt; required for unattended runs in CI. *(`replace`, `rename`, `rollback`, `sessions`, `update`)* |

</details>

<details open>
<summary><b>Safety & backups</b> (9)</summary>

| Flag | Environment | Default | What it does |
| --- | --- | --- | --- |
| `--backup`, `--no-backup` | `SR_BACKUP` | on | Store originals in a session so the run can be rolled back (default on). *(`replace`, `rename`)* |
| `--backup-dir` `DIR` | `SR_BACKUP_DIR` | — | Where to keep sessions (default <target>/.sr). Use an absolute path to keep them out of the tree. *(`replace`, `rename`)* |
| `--keep` `N` | `SR_KEEP` | `20` | Keep at most N sessions; older ones are pruned after a run (default 20, 0 disables pruning). *(`replace`, `rename`, `sessions`)* |
| `--keep-age` `AGE` | `SR_KEEP_AGE` | — | Also drop sessions older than AGE (e.g. 30d). *(`replace`, `rename`, `sessions`)* |
| `--atomic`, `--no-atomic` | `SR_ATOMIC` | on | Write via a temporary file + rename (default) or rewrite the inode in place. *(`replace`)* |
| `--lock`, `--no-lock` | `SR_LOCK` | on | Take an advisory lock so two sr runs cannot interleave (default on). *(`replace`, `rename`)* |
| `--confirm-threshold` `N` | `SR_CONFIRM_THRESHOLD` | `50` | Ask for confirmation when more than N files would change (0 disables). *(`replace`, `rename`)* |
| `--allow-root` | `SR_ALLOW_ROOT` | — | Permit a mutating run with euid 0 (refused by default). *(`replace`, `rename`)* |
| `-f`, `--force` | `SR_FORCE` | — | Override safety guards (drifted files, read-only warnings, existing targets). *(`replace`, `rename`, `rollback`)* |

</details>

<details open>
<summary><b>Output & reporting</b> (8)</summary>

| Flag | Environment | Default | What it does |
| --- | --- | --- | --- |
| `-v`, `--verbose` | `SR_VERBOSE` | — | Show per-file results and the reason skipped files were skipped. *(all)* |
| `-q`, `--quiet` | `SR_QUIET` | — | Only errors; suitable for scripts. *(all)* |
| `--verbosity` `LEVEL` | `SR_VERBOSITY` | `normal` | Set the log level explicitly (overrides -v/-q) — one of `quiet`, `normal`, `verbose`, `debug`. *(all)* |
| `--color`, `--no-color` `WHEN` | `SR_COLOR` | `auto` | Colourise output. Honours NO_COLOR and CLICOLOR_FORCE — one of `auto`, `always`, `never`. *(all)* |
| `--json` | `SR_JSON` | — | Emit a single JSON document on stdout; diagnostics go to stderr. *(all)* |
| `--porcelain` | `SR_PORCELAIN` | — | Emit stable 'path:line:col:text' records, one per match. *(`replace`, `find`, `diff`, `rename`)* |
| `--progress`, `--no-progress` | `SR_PROGRESS` | on | Show a progress bar on a terminal (default on). *(`replace`, `find`, `diff`, `rename`)* |
| `--summary`, `--no-summary` | `SR_SUMMARY` | on | Print the run summary (default on). *(`replace`, `find`, `diff`, `rename`)* |

</details>

<details>
<summary><b>Command-local options</b> (accepted by one command only)</summary>

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**

| Flag | What it does |
| --- | --- |
| `--help-all` | Show help for every subcommand and option |
| `-V`, `--version` | Print version, license and update information |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr replace`**

| Flag | What it does |
| --- | --- |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |
| `--glob` `GLOB` | File name pattern (repeatable); alternative to the positional GLOB |

**`sr find`**

| Flag | What it does |
| --- | --- |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |
| `--glob` `GLOB` | File name pattern (repeatable) |
| `-c`, `--count` | Print only the number of matches per file (and a total) |
| `-l`, `--files-with-matches` | Print only the names of files that contain a match |
| `-A`, `--after-context` `N` | Print N lines after each match |
| `-B`, `--before-context` `N` | Print N lines before each match |
| `--highlight` | Force match highlighting even when writing to a file |

**`sr diff`**

| Flag | What it does |
| --- | --- |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |
| `--session` `SESSION` | Instead of computing a diff, show the diff stored in a session |

**`sr rename`**

| Flag | What it does |
| --- | --- |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |
| `--directories` | Also rename directories that match (default: files only) |

**`sr rollback`**

| Flag | What it does |
| --- | --- |
| `--no-safety-snapshot` | Do not record the pre-rollback state (not recommended) |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr sessions`**

| Flag | What it does |
| --- | --- |
| `--limit` `N` | List at most N sessions (default 20) |
| `--files` | Include the per-file list in `show` |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr update`**

| Flag | What it does |
| --- | --- |
| `--check` | Only report whether an update exists |
| `--version` `VERSION` | Install a specific version (e.g. 7.1.0) |
| `--channel` | Release channel (default: stable) |
| `--source` | Where to fetch release information (default: github) |
| `--repo` `OWNER/NAME` | Override the GitHub repository |
| `--timeout` `SECONDS` | Network timeout (default 20) |
| `--path` `FILE` | Standalone file to update (default: auto-detect) |
| `--no-verify` | Install without SHA-256 verification. Verification is fail-closed by default, so this is the only way past a missing checksum — use it only for a mirror you trust |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr doctor`**

| Flag | What it does |
| --- | --- |
| `--offline` | Skip the network reachability probe |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr completions`**

| Flag | What it does |
| --- | --- |
| `--install` | Write the script into the shell's completion directory |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr config`**

| Flag | What it does |
| --- | --- |
| `--option` `NAME` | Option name for `show`, e.g. `sr config show --option max-size` |
| `--show-origin` | Show where each value comes from |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr selftest`**

| Flag | What it does |
| --- | --- |
| `--quick` | Run only the essential checks |
| `--debug` | Debug logging (same as -vv) |
| `--no-update-check` | Do not check for a newer release |
| `--config` `KEY=VALUE` | Override one configuration value (repeatable) |
| `--config-file` `FILE` | Read an extra configuration file (repeatable) |

**`sr help`**

| Flag | What it does |
| --- | --- |
| `--option` `NAME` | Explain one option, e.g. `sr help --option max-count` |
| `--all` | Same as `sr --help-all` |
| `--no-pager` | Never page the output |

</details>

<!-- END OPTIONS -->