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
# or
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 |
❌ |
Underscores not allowed |
unknown/some-task |
❌ |
Unknown prefix type |
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.
1---2name: conventional-branch3description: 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.4---56# Conventional Branch Naming78Produce Git branch names that follow the [Conventional Branch v1.1.0](https://conventionalbranch.org/) specification: a `<type>/<description>` structure that is human- and machine-readable.910## When to Use1112- Creating a new branch (`git checkout -b`, `git switch -c`, `git branch`).13- Deciding what to call a branch before starting a feature, bug fix, hotfix, release, or chore.14- Validating or correcting an existing branch name against the specification.1516Do **not** rename trunk branches (`main`, `master`, `develop`) — they carry no prefix.1718## Format1920```21<type>/<description>22```2324## Procedure25261. **Pick the prefix** that matches the intent of the work (see Prefixes below).272. **Write the description**: short, clear, lowercase, words separated by hyphens. Include a ticket number when one exists (e.g. `issue-123`).283. **Apply the Basic Rules** and confirm the name matches the validation regex.294. **Create the branch**, for example:30 ```bash31 git switch -c feature/add-login-page32 # or33 git checkout -b fix/issue-123-header-bug34 ```3536## Prefixes3738Purpose prefixes — describe the intent of the work:3940| Prefix | Alias | Use for | Example |41|--------|-------|---------|---------|42| `feature/` | `feat/` | New features | `feature/add-login-page` |43| `bugfix/` | `fix/` | Bug fixes | `fix/header-bug` |44| `hotfix/` | — | Urgent production fixes | `hotfix/security-patch` |45| `release/` | — | Preparing a release (dots allowed for versions) | `release/v1.2.0` |46| `chore/` | — | Non-code tasks: deps, docs, tooling | `chore/update-dependencies` |4748AI agent source prefixes — identify branches generated by AI coding agents:4950| Prefix | Agent |51|--------|-------|52| `ai/` | Any AI agent (vendor-neutral) |53| `copilot/` | GitHub Copilot |54| `cursor/` | Cursor |55| `claude/` | Claude Code (Anthropic) |56| `codex/` | OpenAI Codex |5758Teams may define additional custom types, but document them so tooling and teammates recognize them.5960## Basic Rules61621. **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`).632. **No consecutive, leading, or trailing hyphens or dots.** Avoid `feature/new--login`, `feature/-new-login`, `feature/new-login-`, `release/v1.-2.0`.643. **Clear and concise.** The name should describe the purpose without being verbose.654. **Include ticket numbers when applicable**, e.g. `feature/issue-123-new-login`.6667## Validation6869A name is valid if it is a trunk branch or matches the specification. Practical regex (matches the ABNF grammar below):7071```72^(main|master|develop)$73```74or75```76^(feature|feat|bugfix|fix|hotfix|release|chore|ai|copilot|cursor|claude|codex)/[a-z0-9]+(\.[a-z0-9]+)*(-[a-z0-9]+(\.[a-z0-9]+)*)*$77```7879Quick shell check:80```bash81name="feature/add-login-page"82echo "$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]+)*)*$' \83 && echo "valid" || echo "invalid"84```8586## Examples8788| Branch | Valid | Reason |89|--------|:-----:|--------|90| `main` / `master` / `develop` | ✅ | Trunk branches (no prefix) |91| `feature/add-login-page` | ✅ | New feature |92| `feat/add-login-page` | ✅ | Short alias for feature |93| `bugfix/fix-header-bug` | ✅ | Bug fix |94| `fix/header-bug` | ✅ | Short alias for bugfix |95| `hotfix/security-patch` | ✅ | Urgent fix |96| `release/v1.2.0` | ✅ | Release with version |97| `chore/update-dependencies` | ✅ | Non-code task |98| `feature/issue-123-new-login` | ✅ | Feature with ticket number |99| `copilot/add-login-page` | ✅ | GitHub Copilot |100| `ai/refactor-auth-flow` | ✅ | Generic AI agent prefix |101| `Feature/Add-Login` | ❌ | Uppercase not allowed |102| `feature/new--login` | ❌ | Consecutive hyphens |103| `feature/-new-login` | ❌ | Leading hyphen |104| `feature/new-login-` | ❌ | Trailing hyphen |105| `release/v1.-2.0` | ❌ | Hyphen adjacent to dot |106| `fix/header bug` | ❌ | Spaces not allowed |107| `fix/header_bug` | ❌ | Underscores not allowed |108| `unknown/some-task` | ❌ | Unknown prefix type |109110## Formal Grammar (ABNF)111112```113branch-name = trunk-branch / prefixed-branch114trunk-branch = "main" / "master" / "develop"115prefixed-branch = type "/" description116type = "feature" / "feat" / "bugfix" / "fix"117 / "hotfix" / "release" / "chore"118 / "ai" / "copilot" / "cursor"119 / "claude" / "codex"120description = desc-segment *("-" desc-segment)121desc-segment = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))122ALPHA = %x61-7A ; lowercase a-z123DIGIT = %x30-39 ; 0-9124```125126Consecutive hyphens or dots, and hyphens or dots at the start or end of the description, are not permitted.
open-sdr