GitHub

rrt Git Workflow

rrt branch

rrt branch

Branch command helpers and utilities for conventional branches.

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

  • 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

<type>/[<scope>-]<kebab-case-description>

Example branches:

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

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

These branch names are also valid:

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

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

  • 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

  • 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

  • Branch slugs are limited to 60 characters by default.
  • Custom branch types can be added via configuration.
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

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

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

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 the rename 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

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
  • 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

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.

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

See also

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.
  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.
  sync              Fetch, stash if needed, and pull the current branch safely.
  move              Switch branches safely by stashing and restoring local changes.
  squash-local      Squash local commits since upstream or a base ref into one commit.
  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.

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
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 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

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

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 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

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

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.

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

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

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 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

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 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 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

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

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

↑ Docs index · CLI reference · Changelog · GitHub