rrt hooks

rrt hooks

Overview

repo-release-tools publishes reusable hooks in .pre-commit-hooks.yaml. This page covers pre-commit, lefthook, and husky wiring for those hooks. It is written for maintainers setting up local policy in a repository. Start with the changelog workflow. The hook set follows from that choice.

Choose the workflow first

Workflow	Recommended hooks	Best for
incremental (default)	rrt-branch-name, rrt-commit-subject, plus rrt-update-unreleased or rrt-changelog	teams that maintain changelog state while developing
squash	rrt-branch-name, rrt-commit-subject, optional rrt-dirty-tree / rrt-doctor / rrt-release-check	repos that squash many commits and do changelog work at release time

With changelog_workflow = "squash", the changelog-writing and changelog-check hooks intentionally skip changelog enforcement.

Examples

Two starting configurations cover most repositories. Pick the one that matches the workflow chosen above.

Incremental workflow: keep [Unreleased] current

default_install_hook_types: [pre-commit, commit-msg]

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.18.0
    hooks:
      - id: rrt-branch-name
      - id: rrt-update-unreleased
      - id: rrt-commit-subject

Install both hook types:

pre-commit install --hook-type pre-commit --hook-type commit-msg

This setup keeps CHANGELOG.md moving with development. rrt-update-unreleased auto-writes changelog bullets for changelog-relevant commit types, while rrt-commit-subject enforces Conventional Commits.

If you prefer manual changelog edits instead of auto-writing them, replace rrt-update-unreleased with rrt-changelog.

Squash workflow: keep local policy, skip per-commit changelog noise

default_install_hook_types: [pre-commit, commit-msg]

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.18.0
    hooks:
      - id: rrt-branch-name
      - id: rrt-commit-subject

Use this when pull requests are squash-merged. It keeps ten tiny commit-level changelog bullets from becoming one giant release footnote monster. Pair it with:

• changelog_workflow = "squash" in repo config
• GitHub Action changelog-strategy: "auto" or "release-only"
• rrt bump to generate release-time changelog content

Hook overview

Hook	Stage	Description
rrt-branch-name	pre-commit	Validate branch naming convention
rrt-update-unreleased	commit-msg	Auto-write a bullet under [Unreleased] for changelog-relevant commits
rrt-changelog	pre-commit	Require a staged changelog update for changelog-relevant work
rrt-commit-subject	commit-msg	Validate Conventional Commit subjects
rrt-dirty-tree	pre-push / manual	Fail on uncommitted changes
rrt-doctor	manual	Run rrt doctor core automation checks on rrt config
rrt-release-check	manual	Run rrt release check for version targets, pin targets, and changelog files
rrt-docs-lock	manual	Regenerate the source-owned docs lockfile (.rrt/docs.lock.toml)
rrt-docs-publish	manual	Regenerate CLI reference documentation and topic pages
rrt-docs-inject	manual	Synchronize shared anchor blocks across documentation
rrt-docstring-suggest	manual	Apply scaffolded docstrings to missing or thin module docstrings
rrt-folder-check	pre-commit / pre-push	Validate repository folder structure against [tool.rrt.folders] config
rrt-artifacts-generate	pre-commit	Run generation commands and snapshot hashes to .rrt/artifacts.lock.toml
rrt-artifacts-check	manual	Verify artifact hashes match the committed lock (strict by default)
rrt-artifacts-snapshot	manual	Snapshot artifact hashes without running generation commands
rrt-tree-check	pre-push	Validate project tree structure against the committed .rrt/tree.lock.toml
rrt-drift-check	pre-push	Verify agent-facing surfaces match the committed .rrt/drift.lock.toml
rrt-changelog-postcorrect	manual	Consolidate fragmented changelog entries after a squash merge
rrt-sync	manual	List upstream releases newer than the current version
rrt-config-validate	pre-commit / pre-push	Validate [tool.rrt] config — version targets, pin targets, and structure
rrt-config-reference-check	manual	Fail when docs/rrt-config-reference.toml is stale vs the schema
rrt-changelog-lint	pre-commit	Enforce changelog entry style (sentence case, length, no duplicates)
rrt-tag-check	pre-push	Validate existing git tags follow the configured naming convention

rrt-update-unreleased and rrt-changelog are alternatives for the incremental workflow.

Optional guards

Dirty tree check

rrt-dirty-tree is not enabled in the minimal configs because a normal pre-commit run happens while the working tree is intentionally dirty. It is better suited for pre-push or manual execution when you want to enforce a clean repository before publishing work:

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.18.0
    hooks:
      - id: rrt-dirty-tree
        stages: [pre-push]

Doctor check

rrt-doctor runs rrt doctor against the repository’s core automation wiring. Use it to confirm hook and CI surfaces are configured before a release:

pre-commit run rrt-doctor --hook-stage manual
# or directly:
rrt doctor

Release check

rrt-release-check runs rrt release check against version targets, pin targets, and changelog files in [tool.rrt]. It is also registered at the manual stage so you can invoke it on demand before releases:

pre-commit run rrt-release-check --hook-stage manual
# or directly:
rrt release check

You can also run the same dirty-tree logic directly:

rrt-hooks check-dirty-tree

Tree check

rrt-tree-check validates the project directory structure against the committed .rrt/tree.lock.toml. Run it at pre-push to catch accidental layout changes before they reach the remote:

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.18.0
    hooks:
      - id: rrt-tree-check
        stages: [pre-push]

Generate or refresh the lock with rrt tree --lock.

Drift check

rrt-drift-check verifies that agent-facing surfaces (MCP tool definitions, skills, and related metadata) match the committed .rrt/drift.lock.toml. Pair it with pre-push to prevent publishing stale agent interfaces:

repos:
  - repo: https://github.com/Anselmoo/repo-release-tools
    rev: v1.18.0
    hooks:
      - id: rrt-drift-check
        stages: [pre-push]

Update the lock with rrt drift snapshot.

Upstream sync

rrt-sync lists upstream releases that are strictly newer than the current project version. It is a read-only informational hook registered at the manual stage. Use it in release pipelines to decide whether a bump is needed:

# List newer versions one per line
pre-commit run rrt-sync --hook-stage manual
# or directly:
rrt sync
rrt sync --json

See [tool.rrt.upstream] config and the rrt sync command for details.

Config reference & validation

rrt-config-validate gates commits and pushes by validating the [tool.rrt] config. It checks that version targets resolve, that pin targets reference known files, and that the structure is well-formed. docs/rrt-config-reference.toml is schema-generated. rrt-config-reference-check (manual stage) fails the hook run when that file is stale relative to the current schema.

Regenerating and staging the reference on each commit is repo self-tooling. Wire a local bash -c 'rrt config --reference --check || (rrt config --reference && git add …)' hook in your own .pre-commit-config.yaml if you vendor the reference.

Changelog lint

rrt-changelog-lint enforces changelog entry style on every pre-commit run. It requires sentence case, caps entry length, and rejects duplicate bullets before they accumulate.

Tag check

rrt-tag-check runs at pre-push and validates that existing git tags in the repository follow the naming convention configured under [tool.rrt].

Post-correction mode (squash-merge workflows)

When a pull request is merged via squash merge, GitHub condenses all per-commit changelog entries into the squash commit. The result can be fragmented micro-commit noise in CHANGELOG.md — for example several "CI: add Node 26" / "CI: remove Node 26" pairs that cancel each other out.

rrt-hooks changelog post-correct consolidates those entries by:

1. Inspecting the diff that the squash commit introduced to CHANGELOG.md.
2. Removing exact duplicate bullet entries (case-insensitive).
3. Removing semantically-cancelling pairs — e.g. "CI: add Node 26" followed by "CI: remove Node 26", or bare "add X" / "remove X". Scope prefixes (e.g. CI:, Deps:) must match for entries to be considered a pair.
4. Rewriting CHANGELOG.md in-place with the cleaned content, restricting removals to the exact diff hunk so older release sections are never touched.
5. Optionally creating a follow-up commit (--commit).

Quick usage

# auto mode — use HEAD as the squash commit (default when no SHA given)
rrt-hooks changelog post-correct

# explicit squash commit SHA
rrt-hooks changelog post-correct --squash-commit abc1234

# write a follow-up commit automatically
rrt-hooks changelog post-correct --commit

As a GitHub Actions step (post-merge on default branch)

- name: Consolidate changelog after squash merge
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: uvx --from repo-release-tools rrt-hooks changelog post-correct --commit

Options

Flag	Description
--squash-commit SHA	Explicit commit SHA to inspect (defaults to HEAD)
--output PATH	Changelog file to rewrite (default: CHANGELOG.md)
--commit	Create a follow-up commit with the corrected changelog

---

Lefthook setup

Lefthook can run the same local policy with an installed rrt-hooks binary.

Install repo-release-tools so rrt-hooks is on PATH, then add the commands that match your workflow.

Incremental workflow example

lefthook.yml

commit-msg:
  commands:
    rrt-update-unreleased:
      run: rrt-hooks update-unreleased --message-file {1}
    rrt-commit-subject:
      run: rrt-hooks commit-msg {1}

pre-commit:
  commands:
    rrt-branch-name:
      run: rrt-hooks pre-commit

pre-push:
  commands:
    rrt-changelog:
      run: rrt-hooks check-changelog --subject "$(git log -1 --format=%s)" --strategy unreleased

Squash workflow example

lefthook.yml

commit-msg:
  commands:
    rrt-commit-subject:
      run: rrt-hooks commit-msg {1}

pre-commit:
  commands:
    rrt-branch-name:
      run: rrt-hooks pre-commit

---

Husky setup

Husky v9 runs shell scripts from .husky/ and works with any installed CLI, including rrt-hooks.

Install repo-release-tools so rrt-hooks is on PATH, then initialise Husky once and add the script files that match your workflow:

pip install repo-release-tools   # or: uv pip install repo-release-tools
npx husky init

Husky v9 hook file format: npx husky init creates .husky/pre-commit with a shell shebang. Keep the header it generates and replace only the command body. Each hook file must be executable — run chmod +x .husky/<hook> after creating it.

Incremental workflow example

.husky/pre-commit

#!/usr/bin/env sh
rrt-hooks pre-commit

.husky/commit-msg

#!/usr/bin/env sh
rrt-hooks update-unreleased --message-file "$1"
rrt-hooks commit-msg "$1"

#!/usr/bin/env sh
# .husky/pre-push  (optional — add when you want an unreleased guard)
rrt-hooks check-changelog --subject "$(git log -1 --format=%s)" --strategy unreleased

After creating each file, make it executable:

chmod +x .husky/pre-commit .husky/commit-msg  # add .husky/pre-push if used

Squash workflow example

.husky/pre-commit

#!/usr/bin/env sh
rrt-hooks pre-commit

.husky/commit-msg

#!/usr/bin/env sh
rrt-hooks commit-msg "$1"

Comparison: pre-commit · lefthook · husky

Policy	pre-commit	lefthook	husky
Auto-write changelog	rrt-update-unreleased (commit-msg)	rrt-update-unreleased --message-file {1}	rrt-hooks update-unreleased --message-file "$1"
Validate commit subject	rrt-commit-subject (commit-msg)	rrt-commit-subject {1}	rrt-hooks commit-msg "$1"
Validate branch name	rrt-branch-name (pre-commit)	rrt-hooks pre-commit	rrt-hooks pre-commit
Pre-push unreleased guard	rrt-changelog or rrt-dirty-tree	rrt-hooks check-changelog --subject "$(git log -1 --format=%s)" --strategy unreleased	rrt-hooks check-changelog --subject "$(git log -1 --format=%s)" --strategy unreleased

Caveats

• Under changelog_workflow = "squash" the changelog hooks stay configured but do nothing. You can leave them during migration. The cleaner setup is to remove them and keep only the non-changelog policy hooks.
• rrt-update-unreleased and rrt-changelog overlap. Enable one, not both.
• Commit-msg hooks only fire when commit-msg is listed in default_install_hook_types. A missing entry skips them silently.
• rrt-dirty-tree fails an ordinary pre-commit run, because the working tree is dirty at that point. Register it at pre-push or the manual stage.
• Lefthook and husky call rrt-hooks directly. Install repo-release-tools first so the binary is on PATH.
• Husky hook files must be executable. Run chmod +x .husky/<hook> after creating each one.

Related docs

• Hook & Action reference for ready-to-paste agent prompts
• GitHub Action for the CI counterpart of these hooks
• rrt doctor to verify hook and CI wiring
• rrt branch for the branch naming the hooks enforce