# sr documentation

The authoritative manual ships **inside the tool** and is generated from the
same schema as the parser, so it always matches the version you have installed:

```sh
sr help                # overview and quick start
sr help topics         # the 27-topic index
sr help <topic>        # matching, targets, backup, rollback, update, …
sr help <command>      # everything one subcommand accepts
sr help --<option>     # one option in depth, with an example
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
```

This directory holds the artefacts that need to live in the repository:

| File | What it is | Generated by |
| --- | --- | --- |
| [`man/sr.1`](man/sr.1) | the man page | `tools/build_manpage.py` (`make man`) |
| [`OPTIONS.md`](OPTIONS.md) | the full option table | `scripts/gen_options_table.py` (`make docs`) |
| [`EXIT_CODES.md`](EXIT_CODES.md) | the frozen exit-code contract, per command | `scripts/gen_exit_codes.py` (`make docs`) |
| [`MIGRATION-6-to-7.md`](MIGRATION-6-to-7.md) | migrating from the Bash implementation | hand-written |

All of them are checked in CI: the man page, the option table and the exit-code
document are regenerated and diffed, so a stale artefact fails the build.

## Reading order

New here?

1. [`README.md`](../README.md#quick-start) — install and the five-minute tour
2. `sr help quickstart` — preview → replace → rollback
3. `sr help matching` — literal vs `--regex`/`--ere`/`--pcre`, ranges, counts
4. `sr help targets` — globs, exclusions, `.gitignore`, size and age filters

Operating it?

5. `sr help backup` and `sr help rollback` — sessions, drift detection, undoing
   an undo
6. `sr help json` — automation, exit codes, CI recipes
7. `sr help config` — precedence and the `.srrc` format
8. `sr help update` — how self-update verifies what it downloads

Going deeper?

9. `sr help architecture` — module map and data flow
10. `sr help performance` — where the time goes
11. `sr help security` — the safety model, guarantee by guarantee
12. [`CONTRIBUTING.md`](../CONTRIBUTING.md) — adding an option or a command
13. [`SECURITY.md`](../SECURITY.md) — reporting a vulnerability