Skip to content
repo-release-tools
GitHub

rrt branch

Branch command helpers and utilities for conventional branches.

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.

  • 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
<type>/[<scope>-]<kebab-case-description>

Example branches:

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

Conventional branch types are accepted out of the box:

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

These branch names are also valid:

  • main, master, develop
  • release branches built from each version group’s release_branch template (default release/v<version>), with a SemVer, PEP 440 or CalVer version

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

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

A repository defines its own types in [tool.rrt]. Each table entry is a full definition:

[[tool.rrt.commit_types]]
name = "security"
description = "Security fix or hardening"
changelog_section = "Security" # false keeps it out of the changelog
bump = "patch" # none | patch | minor
[[tool.rrt.branch_types]]
name = "design"
description = "Design records and decisions"
commit_types = ["docs", "chore"] # omitted allows any commit type
slug = "kebab" # kebab | any

An entry with a built-in name overrides only the fields it sets. Hooks, MCP validators, changelog rendering, bump inference and rrt branch new read the same definitions. On a design/... branch the commit-msg hook rejects any type outside commit_types. The flat extra_branch_types and extra_commit_types lists stay as shorthand. rrt config lists every resolved type with its description.

  • 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.
  • 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"
  • Branch slugs are limited to 60 characters by default.
  • Custom branch types can be added via configuration.
  • Agent and bot prefixes are accepted by the hooks but never created by rrt branch new.

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.