Press a new identity onto an existing repository. template-press is a standalone command-line utility: you point it at a target repo, it discovers and validates that repo's current identity, rewrites every occurrence to a new identity, and — only after verifying that none of the old identity survives — writes a receipt. A wrong or partial run fails loudly instead of silently corrupting the target.
It is not a project template you fork; it is a tool you run against other repos, one at a time. The rebrand engine is pure standard library, so the installed package has zero runtime dependencies.
uvx --from template-press press --help # run without installing
# or
pip install template-press# preview the plan (writes nothing)
press rebrand --target ../my-repo --config press-answers.toml --dry-run
# apply, verify, and write a receipt
press rebrand --target ../my-repo --config press-answers.tomlpress-answers.toml describes the destination identity:
[answers]
package_name = "new_pkg"
repo_name = "new-repo"
app_name = "newcli"
author = "Jane Dev"
email = "jane@example.com"
owner = "janedev"Keep your filled-in press-answers.toml out of the target (it is transient
operator input, not committed state). A repo may commit a
press/press-answers.example.toml placeholder to advertise the field
shape — copy it, fill it, and pass it via --config. It has the same
[answers] fields shown above.
The target's current identity is read from a committed
<target>/press/press-source.toml. On a first run, --dry-run prints a proposed
source-config from discovery; review it and re-run with --accept-discovery
to write and use it.
- Config-first identity, discovery as a guard. The committed source-config is authoritative; discovery cross-checks it against the target and refuses to run on a mismatch, so the press never rewrites the wrong repo.
- Verify-then-mark. After rewriting, a no-leak scan confirms no source identity remains. Any leftover ⇒ exit 1 and no receipt — a partial rebrand is a loud failure, not a false success.
- Boundary-safe replacement. Short tokens (
press, an owner likego) match only at word boundaries, so ordinary prose (compress,ongoing) is never touched.
The exit code is the contract:
| Code | Meaning |
|---|---|
0 |
Verified — rebrand complete, no source identity remains, receipt written. |
1 |
Leaks found after applying. No receipt; restore with git -C <target> checkout . && git clean -fd. |
2 |
Precondition/config error (missing target, dirty tree, identity mismatch, existing receipt without --force, or unavailable atomic rename without --force). Nothing written. |
--dry-run exits 0 after printing the plan without touching the target (no receipt). It warns on a statically unsupported host; target-filesystem capability is probed only during real apply. Forced apply uses a guarded non-atomic fallback and warns about its destination-overwrite race.
- Full docs: https://template-press.readthedocs.io/
- Design contract:
docs/design/0006-external-target-model.md - Agent runbooks:
press-target(drive a press) andrebrand-matrix(the R1/R2/R3 acceptance matrix)
See AGENTS.md for the canonical toolchain and verification flow
(just setup → just check → commit) and
.github/CONTRIBUTING.md for the human contributor
guide.
MIT — see LICENSE.