| name | conventional-branch |
| description | Generate and validate Git branch names using the Conventional Branch specification (v1.1.0). Use when creating a branch, naming a branch, running git checkout -b / git switch -c, starting work on a feature/bugfix/hotfix/release/chore, or verifying whether a branch name is valid. Produces lowercase, prefixed names like feature/add-login-page, fix/header-bug, or release/v1.2.0. |
| argument-hint | describe the work (e.g. "add login page" or "fix header bug on issue-123") |
Conventional Branch Naming
Produce Git branch names that follow the Conventional Branch v1.1.0 specification: a <type>/<description> structure that is human- and machine-readable.
When to Use
- Creating a new branch (
git checkout -b, git switch -c, git branch).
- Deciding what to call a branch before starting a feature, bug fix, hotfix, release, or chore.
- Validating or correcting an existing branch name against the specification.
Do not rename trunk branches (main, master, develop) — they carry no prefix.
Format
<type>/<description>
Procedure
- Pick the prefix that matches the intent of the work (see Prefixes below).
- Write the description: short, clear, lowercase, words separated by hyphens. Include a ticket number when one exists (e.g.
issue-123).
- Apply the Basic Rules and confirm the name matches the validation regex.
- Create the branch, for example:
git switch -c feature/add-login-page
git checkout -b fix/issue-123-header-bug
Prefixes
Purpose prefixes — describe the intent of the work:
| Prefix | Alias | Use for | Example |
|---|
feature/ | feat/ | New features | feature/add-login-page |
bugfix/ | fix/ | Bug fixes | fix/header-bug |
hotfix/ | — | Urgent production fixes | hotfix/security-patch |
release/ | — | Preparing a release (dots allowed for versions) | release/v1.2.0 |
chore/ | — | Non-code tasks: deps, docs, tooling | chore/update-dependencies |
AI agent source prefixes — identify branches generated by AI coding agents:
| Prefix | Agent |
|---|
ai/ | Any AI agent (vendor-neutral) |
copilot/ | GitHub Copilot |
cursor/ | Cursor |
claude/ | Claude Code (Anthropic) |
codex/ | OpenAI Codex |
Teams may define additional custom types, but document them so tooling and teammates recognize them.
Basic Rules
- Lowercase alphanumerics, hyphens, and dots only. Use
a-z, 0-9, and - to separate words. No uppercase, spaces, underscores, or other special characters. Dots (.) are allowed in the description for version numbers (e.g. release/v1.2.0).
- No consecutive, leading, or trailing hyphens or dots. Avoid
feature/new--login, feature/-new-login, feature/new-login-, release/v1.-2.0.
- Clear and concise. The name should describe the purpose without being verbose.
- Include ticket numbers when applicable, e.g.
feature/issue-123-new-login.
Validation
A name is valid if it is a trunk branch or matches the specification. Practical regex (matches the ABNF grammar below):
^(main|master|develop)$
or
^(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*$
Quick shell check:
name="feature/add-login-page"
echo "$name" | grep -Eq '^(main|master|develop)$|^(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*$' \
&& echo "valid" || echo "invalid"
Examples
| Branch | Valid | Reason |
|---|
main / master / develop | ✅ | Trunk branches (no prefix) |
feature/add-login-page | ✅ | New feature |
feat/add-login-page | ✅ | Short alias for feature |
bugfix/fix-header-bug | ✅ | Bug fix |
fix/header-bug | ✅ | Short alias for bugfix |
hotfix/security-patch | ✅ | Urgent fix |
release/v1.2.0 | ✅ | Release with version |
chore/update-dependencies | ✅ | Non-code task |
feature/issue-123-new-login | ✅ | Feature with ticket number |
copilot/add-login-page | ✅ | GitHub Copilot |
ai/refactor-auth-flow | ✅ | Generic AI agent prefix |
Feature/Add-Login | ❌ | Uppercase not allowed |
feature/new--login | ❌ | Consecutive hyphens |
feature/-new-login | ❌ | Leading hyphen |
feature/new-login- | ❌ | Trailing hyphen |
release/v1.-2.0 | ❌ | Hyphen adjacent to dot |
fix/header bug | ❌ | Spaces not allowed |
fix/header_bug | ❌ |
Formal Grammar (ABNF)
branch-name = trunk-branch / prefixed-branch
trunk-branch = "main" / "master" / "develop"
prefixed-branch = type "/" description
type = "feature" / "feat" / "bugfix" / "fix"
/ "hotfix" / "release" / "chore"
/ "ai" / "copilot" / "cursor"
/ "claude" / "codex"
description = desc-segment *("-" desc-segment)
desc-segment = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA = %x61-7A ; lowercase a-z
DIGIT = %x30-39 ; 0-9
Consecutive hyphens or dots, and hyphens or dots at the start or end of the description, are not permitted.
