Skip to content
repo-release-tools
GitHub

rrt Git Workflow

rrt Git Workflow

Section titled “rrt Git Workflow”

rrt branch

Section titled “rrt branch”

Branch command helpers and utilities for conventional branches.

Overview

Section titled “Overview”

The rrt branch command family provides a suite of helpers for managing semantic, conventionally-named Git branches. By enforcing a consistent naming structure—such as feat/add-parser or fix/config-loader—the tool ensures that the repository’s branch history remains searchable, readable, and aligned with standard conventional-commits policies.

These helpers are particularly useful for teams practicing trunk-based development, where branch names often serve as the primary signal for automated release notes and CI workflow routing.

Responsibilities

Section titled “Responsibilities”
  • validate branch names against project-specific prefix and slug rules
  • scaffold new branches using the canonical <type>/<kebab-slug> format
  • automate the renaming of branches while preserving description context
  • “rescue” uncommitted work or divergent commits into new, semantic branches
  • provide actionable suggestions when a branch name violates repository policy

Standard Format

Section titled “Standard Format”
<type>/[<scope>-]<kebab-case-description>

Example branches:

  • feat/add-config-discovery
  • fix/handle-tag-workflows
  • docs/split-readme-into-docs

Built-in branch types

Section titled “Built-in branch types”

Conventional branch types are accepted out of the box:

  • feat, fix, chore, docs, refactor, test, ci, perf, style, build

Special names

Section titled “Special names”

These branch names are also valid:

  • main, master, develop
  • release/v<semver> (validated as a semver-aware special case)

AI helper and Bot branches

Section titled “AI helper and Bot branches”

Branches created by assistant-driven workflows or dependency bots are accepted with these prefixes:

  • claude/..., codex/..., copilot/...
  • dependabot/..., renovate/...

Custom prefixes can be added via the extra_branch_types config key.

Behavior

Section titled “Behavior”
  • new: Creates and switches to a new branch. Moves dirty changes if requested.
  • rename: Rebuilds the current branch name based on new type, scope, or description.
  • rescue: Moves commits ahead of upstream to a fresh semantic branch.
  • dry-run: Previews all Git operations without modifying the repository.

Examples

Section titled “Examples”
  • rrt branch new feat "add parser"
  • rrt branch new fix "repair config loader" --scope api
  • rrt branch rename --type fix --scope api "fix config loader"
  • rrt branch rescue feat "rescue work in progress"

Caveats

Section titled “Caveats”
  • Branch slugs are limited to 60 characters by default.
  • Custom branch types can be added via configuration.
Section titled “Related docs”
Usage:  rrt branch [OPTIONS] <branch_command>


Branch management helpers for conventional branch naming.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  new         Create a new conventionally named branch.
  rescue      Move commits to a new branch and reset the current branch.
  rename      Rename the current branch: change type, scope, description, or any combination.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt branch new feat "add parser"
  $ rrt branch new fix "repair config loader" --scope api
  $ rrt branch rename --type fix --scope api "fix config loader"
  $ rrt branch rescue feat "rescue work in progress"

rrt branch new

Section titled “rrt branch new”
Usage:  rrt branch new [OPTIONS] TYPE <description>


Create a new conventionally named branch from a commit type, optional scope, and description.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  TYPE
  <description>  Short branch description.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --scope SCOPE  Optional scope.
  --dry-run      Preview without touching git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt branch new feat "add parser"
  $ rrt branch new fix "repair config loader" --scope api
  $ rrt branch rename --type fix --scope api "fix config loader"
  $ rrt branch rescue feat "rescue work in progress"

rrt branch rescue

Section titled “rrt branch rescue”
Usage:  rrt branch rescue [OPTIONS] TYPE <description>


Rescue commits onto a new branch and reset the current branch to a safe point.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  TYPE
  <description>  Short branch description.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --scope SCOPE  Optional scope.
  --dry-run      Preview without touching git.
  --since SHA    Rescue commits since this SHA instead of origin/<branch>.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt branch new feat "add parser"
  $ rrt branch new fix "repair config loader" --scope api
  $ rrt branch rename --type fix --scope api "fix config loader"
  $ rrt branch rescue feat "rescue work in progress"

rrt branch rename

Section titled “rrt branch rename”
Usage:  rrt branch rename [OPTIONS] <description>


Rename the current branch using conventional branch naming rules.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <description>  New branch description words (replaces the current description).


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --type TYPE    New conventional commit type (e.g. feat, fix, build).
  --scope SCOPE  New scope to prefix the slug with.
  --no-scope     Remove the scope from the new branch name (requires description words).
  --dry-run      Preview without touching git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt branch new feat "add parser"
  $ rrt branch new fix "repair config loader" --scope api
  $ rrt branch rename --type fix --scope api "fix config loader"
  $ rrt branch rescue feat "rescue work in progress"

rrt git

Section titled “rrt git”

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

Overview

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.
Section titled “Related docs”
Usage:  rrt git [OPTIONS] <git_command>


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


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  status                Show a compact branch and worktree status view.
  diff                  Show a compact diff using rrt glyph formatting.
  log                   Show a compact commit history view.
  commits-since         List commits since a ref, optionally excluding paths such as generated files.
  doctor                Run a compact repository health report for rrt workflows.
  sync-status           Analyze unresolved conflicts and whether sync/rebase work is needed.
  check-dirty-tree      Exit non-zero when the working tree is dirty. Useful in hooks and CI.
  commit                Create a conventional commit, inferring type from the current branch.
  commit-all            Stage all files and create a conventional commit from the branch context.
  squash-local          Squash local commits since upstream or a base ref into one commit.
  sync                  Fetch, stash if needed, and pull the current branch safely.
  move                  Switch branches safely by stashing and restoring local changes.
  undo-safe             Undo a commit while keeping work staged or in the working tree.
  rebootstrap           Destroy current git history and create a fresh repository history.
  purge-cache           Expire reflogs and run git garbage collection.
  publish-snapshot      Force-push a single-commit snapshot of tracked content to a secondary remote.
  land                  Fast-forward a branch onto its target, remove its worktree and delete it.
  backport-from-target  List commits pending backport from a publish-snapshot target.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help            Show this message and exit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git status
  $ rrt git diff --against HEAD~1
  $ rrt git commit --type fix "make output clearer"
  $ rrt git sync
  $ rrt git undo-safe
  $ rrt git land feat/parser --dry-run
  $ rrt git commits-since v1.2.0 --exclude HANDOFF.md
  $ rrt git publish-snapshot --remote mirror --dry-run
  $ rrt git backport-from-target demo

rrt git status

Section titled “rrt git status”
Usage:  rrt git status [OPTIONS]


Show the current branch, upstream, and compact typed worktree changes for the repository.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git status

rrt git diff

Section titled “rrt git diff”
Usage:  rrt git diff [OPTIONS]


Render a compact tracked-file diff with rrt glyphs for working-tree, staged, or ref-based changes.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --staged       Show staged changes instead of working-tree changes.
  --against REF  Diff against a specific commit or ref.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git diff
  $ rrt git diff --staged
  $ rrt git diff --against HEAD~1

rrt git log

Section titled “rrt git log”
Usage:  rrt git log [OPTIONS]


Show recent commits in a compact rrt log view with short SHAs, subjects, and refs.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help   Show this message and exit.
  -n, --limit  Number of commits to show.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git log
  $ rrt git log --limit 20

rrt git commits-since

Section titled “rrt git commits-since”
Usage:  rrt git commits-since [OPTIONS] <ref>


List commits in <ref>..HEAD. --exclude drops commits that only touch the given git glob pathspecs, so a file that records HEAD can leave itself out.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <ref>                Starting ref (exclusive), e.g. a tag.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help           Show this message and exit.
  --exclude PATTERN    Git glob pathspec (repo-root relative) to leave out. Repeatable.
  --exclude-generated  Also leave out every [tool.rrt.git].generated pattern.
  --count              Print only the number of commits.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git commits-since v1.2.0
  $ rrt git commits-since origin/main --exclude HANDOFF.md --count
  $ rrt git commits-since HEAD~5 --exclude-generated

rrt git doctor

Section titled “rrt git doctor”
Usage:  rrt git doctor [OPTIONS]


Run branch, upstream, worktree, conflict, commit-subject, and changelog checks for an rrt workflow.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help        Show this message and exit.
  --changelog-file  Changelog path used for doctor checks.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git doctor
  $ rrt git doctor --changelog-file docs/CHANGELOG.md

rrt git sync-status

Section titled “rrt git sync-status”
Usage:  rrt git sync-status [OPTIONS]


Report merge or rebase blockers plus ahead/behind drift against the upstream branch or --base-ref.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help      Show this message and exit.
  --base-ref REF  Ref to analyze against. Defaults to the current upstream branch.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git sync-status
  $ rrt git sync-status --base-ref origin/main

rrt git check-dirty-tree

Section titled “rrt git check-dirty-tree”
Usage:  rrt git check-dirty-tree [OPTIONS]


Exit non-zero when the working tree is dirty and print a compact status summary for hooks or CI.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help          Show this message and exit.
  --ignore-generated  Do not count paths matching [tool.rrt.git].generated as dirty; list them instead.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git check-dirty-tree
  $ rrt git check-dirty-tree --ignore-generated

rrt git commit

Section titled “rrt git commit”
Usage:  rrt git commit [OPTIONS] <description>


Create one conventional commit from the provided description, inferring the type from the current branch when possible.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <description>  Commit description words.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --type TYPE    Explicit conventional commit type. Defaults to the current branch type.
  --scope SCOPE  Optional commit scope.
  --breaking     Mark the commit as breaking.
  --dry-run      Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git commit "refresh help examples"
  $ rrt git commit --type fix --scope cli "handle empty config"
  $ rrt git commit --breaking "ship parser v2"

rrt git commit-all

Section titled “rrt git commit-all”
Usage:  rrt git commit-all [OPTIONS] <description>


Stage all tracked and untracked changes, then create one conventional commit from the current branch context.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <description>  Commit description words.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --type TYPE    Explicit conventional commit type. Defaults to the current branch type.
  --scope SCOPE  Optional commit scope.
  --breaking     Mark the commit as breaking.
  --dry-run      Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git commit-all "refresh release metadata"
  $ rrt git commit-all --type chore --scope deps "update lockfiles"

rrt git squash-local

Section titled “rrt git squash-local”
Usage:  rrt git squash-local [OPTIONS] <description>


Squash commits ahead of the upstream branch or --base-ref into one conventional commit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <description>   Commit description words.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help      Show this message and exit.
  --type TYPE     Explicit conventional commit type. Defaults to the current branch type.
  --scope SCOPE   Optional commit scope.
  --breaking      Mark the commit as breaking.
  --dry-run       Preview without changing git.
  --base-ref REF  Base ref to squash against. Defaults to the current upstream branch.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git squash-local "ship parser"
  $ rrt git squash-local --base-ref origin/main --type fix "repair sync handling"

rrt git sync

Section titled “rrt git sync”
Usage:  rrt git sync [OPTIONS]


Fetch, auto-stash when needed, and pull the current branch from its upstream using rebase by default.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.
  --merge     Use plain git pull instead of git pull --rebase.
  --dry-run   Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git sync
  $ rrt git sync --merge
  $ rrt git sync --dry-run

rrt git move

Section titled “rrt git move”
Usage:  rrt git move [OPTIONS] <target>


Switch to another branch, optionally creating it, while auto-stashing and restoring local changes when needed.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <target>      Target branch name.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help    Show this message and exit.
  -b, --create  Create the target branch before switching to it.
  --dry-run     Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git move release/v1.2.0
  $ rrt git move -b feat/help-copy --dry-run

rrt git undo-safe

Section titled “rrt git undo-safe”
Usage:  rrt git undo-safe [OPTIONS]


Reset to HEAD~1 or another target while keeping changes staged (--keep-staged) or in the working tree.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help     Show this message and exit.
  --target REF   Ref to reset to. Defaults to HEAD~1.
  --keep-staged  Use git reset --soft so changes stay staged.
  --dry-run      Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git undo-safe
  $ rrt git undo-safe --keep-staged
  $ rrt git undo-safe --target HEAD~2 --dry-run

rrt git rebootstrap

Section titled “rrt git rebootstrap”
Usage:  rrt git rebootstrap [OPTIONS]


Back up the current .git directory, reinitialize the repository, and create a fresh history snapshot or empty bootstrap commit.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help                          Show this message and exit.
  --yes-i-know-this-destroys-history  Required confirmation for the destructive history reset.
  --allow-remote                      Allow rebootstrap even when remotes are configured.
  --hard-init                         Recreate .git and make only one empty initial commit, leaving files untracked.
  --branch BRANCH                     Initial branch name for the new repository. Defaults to the current branch.
  --message                           Commit message for the new initial commit.
  --empty-first                       Create an empty bootstrap commit before adding files.
  --empty-message                     Commit message for the optional empty bootstrap commit.
  --dry-run                           Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git rebootstrap --yes-i-know-this-destroys-history --dry-run
  $ rrt git rebootstrap --yes-i-know-this-destroys-history --empty-first
  $ rrt git rebootstrap --yes-i-know-this-destroys-history --hard-init --branch main

rrt git purge-cache

Section titled “rrt git purge-cache”
Usage:  rrt git purge-cache [OPTIONS]


Expire local reflogs and run git gc to reclaim repository cache space.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help  Show this message and exit.
  --dry-run   Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git purge-cache
  $ rrt git purge-cache --dry-run

rrt git publish-snapshot

Section titled “rrt git publish-snapshot”
Usage:  rrt git publish-snapshot [OPTIONS] <target>


Create an orphan branch from tracked content, commit it once, and force-push it to a secondary remote. Refuses to run if --remote resolves to the same URL as the configured primary remote (tool.rrt.primary_remote, default: origin), and requires --yes-i-know-this-overwrites-remote-history to do anything beyond a preview. Safety notes: force-pushing does not immediately purge old objects on the remote host — they can remain fetchable by direct SHA until the host runs garbage collection. If secrets were ever committed, run git filter-repo or the BFG Repo-Cleaner first; this command only controls what is visible going forward. Clones or forks made before the force-push retain the old history locally, which is outside this tool's control.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <target>                                     Named [tool.rrt.publish_targets.<name>] entry to resolve remote/branch/message from.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help                                   Show this message and exit.
  --remote                                     Remote name or URL to force-push to.
  --branch                                     Remote branch to force-push to. Defaults to main.
  --message                                    Commit message for the snapshot commit.
  --exclude PATTERN                            Glob (fnmatch, repo-relative) to exclude from the snapshot. Repeatable; extends the resolved target's [tool.rrt.publish_targets.<name>].exclude list.
  --yes-i-know-this-overwrites-remote-history  Required confirmation to actually force-push. Without it, behaves as --dry-run.
  --dry-run                                    Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git publish-snapshot --remote mirror --dry-run
  $ rrt git publish-snapshot demo --yes-i-know-this-overwrites-remote-history
  $ rrt git publish-snapshot --remote mirror --branch main --message "Initial commit" --yes-i-know-this-overwrites-remote-history
  $ rrt git publish-snapshot --remote mirror --exclude 'docs/internal/*' --dry-run

rrt git land

Section titled “rrt git land”
Usage:  rrt git land [OPTIONS] <branch>


Land a finished branch in one process: fast-forward --onto, restore generated paths if asked, remove the branch's worktree, and delete the branch. All checks run before any change; re-running after a failure skips finished steps.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <branch>             Local branch to land.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help           Show this message and exit.
  --onto BRANCH        Branch to fast-forward (default: main).
  --restore-generated  Discard changes to [tool.rrt.git].generated paths in the worktree first: restore tracked files and delete untracked ones.
  --keep-branch        Keep the branch after landing it.
  --dry-run            Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git land feat/parser --dry-run
  $ rrt git land feat/parser
  $ rrt git land feat/parser --onto develop --restore-generated
  $ rrt git land feat/parser --keep-branch

rrt git backport-from-target

Section titled “rrt git backport-from-target”
Usage:  rrt git backport-from-target [OPTIONS] <target>


Fetch a [tool.rrt.publish_targets.<name>] entry's remote/branch and list the commits present there but not on the primary's tracked branch, along with the exact git checkout -b / git cherry-pick commands to run next. Never cherry-picks, merges, or pushes on its own -- reviewing and landing a change that skipped the primary's own CI needs a human decision.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arguments
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  <target>        Named [tool.rrt.publish_targets.<name>] entry to resolve remote/branch from.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Options
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  -h, --help      Show this message and exit.
  --remote        Remote name or URL to fetch from. Overrides the target's configured remote.
  --branch        Remote branch to fetch. Overrides the target's configured branch.
  --base-ref REF  Primary-side ref to compare against. Defaults to the current branch.
  --dry-run       Preview without changing git.


────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Examples
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  $ rrt git backport-from-target demo
  $ rrt git backport-from-target demo --dry-run
  $ rrt git backport-from-target demo --base-ref origin/main

Badge families are intentionally complete for the current icon registry across platform, registry, and language labels; see src/repo_release_tools/tools/platform.py if you think one is missing.

Chat is powered by Context7, a third-party service with its own terms and privacy policy.