rrt git

rrt git

Git workflow helpers for repository status, commit, sync, and history operations.

Overview

repo-release-tools ships a small set of opinionated Git workflows for branch health, commit drafting, sync, and history repair. The tool group favors compact, human-readable summaries with explicit safety checks before any destructive operation.

Most commands are designed to run from a Git work tree and emit a short summary first, followed by the details needed to act on the result.

Workflow map

• Inspect: rrt git status, diff, log, doctor, sync-status, check-dirty-tree (--ignore-generated), commits-since
• Draft commits: rrt git commit, commit-all, squash-local
• Move and sync: rrt git sync, move, undo-safe, rebootstrap
• Branch workflows: rrt branch new, rescue, rename, and rrt git land to fast-forward, remove the worktree, and delete the branch in one process
• Publish: rrt git publish-snapshot force-pushes a single-commit, no-history snapshot of tracked content to a secondary remote (e.g. a public mirror); --exclude drops specific paths (secrets, internal docs) from that snapshot. rrt git backport-from-target is the read-only counterpart: it fetches a publish target and lists commits pending backport to the primary, along with the exact commands to cherry-pick them manually.

Generated paths

[tool.rrt.git].generated lists files that tooling or hooks regenerate. Each entry is a git glob pathspec anchored at the repository root. A * stops at /, while ** crosses directories. The list is empty unless you declare it.

[tool.rrt.git]
generated = ["HANDOFF.md", ".rrt/*.lock.toml"]

Git does the matching on every surface, so a pattern means the same everywhere. check-dirty-tree --ignore-generated lists matching paths instead of failing. land --restore-generated restores tracked matches and deletes untracked ones. commits-since --exclude-generated leaves matching paths out of the count.

Responsibilities

• provide a high-level API for common Git operations used in release flows
• enforce repository policies during commit drafting and branch management
• automate repetitive tasks like auto-stashing during branch switches
• generate human-friendly summaries of repository state and history
• ensure safe operation through dry-run modes and state validation

Notable behavior

• Commit Drafting: rrt git commit infers the commit type from the current branch only when the branch follows the conventional type/slug format.
• State Management: sync and move automatically stash local changes before execution and restore them afterward.
• History Repair: undo-safe and rebootstrap provide controlled ways to rewrite history, with rebootstrap requiring explicit confirmation.
• Validation: Refuses to continue in unsafe states, such as unresolved conflicts or in-progress merges.
• Latest tag lookup: latest_tag and latest_final_tag pick a group’s newest release tag. Only tags starting with the group’s tag_prefix count. The remainder must parse as SemVer or CalVer; anything else is skipped. Tags sort by version precedence, so v1.0.0 beats v1.0.0-rc.2. latest_final_tag ignores pre-releases. rrt bump, rrt release notes and rrt tag all share this lookup.

Examples

• rrt git status
• rrt git commit "refresh help examples"
• rrt git sync --dry-run
• rrt git squash-local --base-ref origin/main "ship parser"
• rrt git rebootstrap --yes-i-know-this-destroys-history --dry-run
• rrt git land feat/parser --restore-generated
• rrt git commits-since v1.2.0 --exclude HANDOFF.md --count
• rrt git check-dirty-tree --ignore-generated

Caveats

• undo-safe and rebootstrap rewrite repository history. rebootstrap requires explicit confirmation before it destroys anything.
• sync and move stash your local changes automatically and restore them afterwards. The working tree is touched even on a run you expected to be read-only.
• rrt git commit only infers the commit type from the branch when that branch follows the conventional type/slug format.
• These commands refuse to continue in unsafe states, such as unresolved conflicts or an in-progress merge.
• The latest-tag lookup matches the prefix literally, not as a glob. With prefix v, a tag named vnext is ignored rather than breaking the range. Build metadata never decides precedence; equal versions fall back to tag name.
• land is local only and never pushes. It deletes the branch with -D only after checking that --onto contains it, because -d checks against HEAD.
• A file that records HEAD can never be committed current. Exclude it with commits-since --exclude, and “one commit behind” becomes its resting state.
• Shell exit codes hide errors that rrt reports explicitly. After a pipeline, $? is the last element’s exit, so gate lines run with pipefail.
• grep -q exits 2 on a missing file and 1 on no match. An if reads both as false.
• git merge-base --is-ancestor exits 128 on error. The is_ancestor helper raises on it instead of answering “no”.
• git add <dir> refuses a gitignored directory even when files inside are tracked. Use git add -u <dir> for tracked files there.
• zsh does not word-split unquoted variables. rrt gate run executes string lines through explicit bash, never the caller’s shell.

Related docs

• Conventional branches
• Generated CLI reference