conventional-branch

# Conventional Branch Naming Produce 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. ## 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 1. **Pick the prefix** that matches the intent of the work (see Prefixes below). 2. **Write the description**: short, clear, lowercase, words separated by hyphens. Include a ticket number when one exists (e.g. `issue-123`). 3. **Apply the Basic Rules** and confirm the name matches the validation regex. 4. **Create the branch**, for example: ```bash 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 1. **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`). 2. **No consecutive, leading, or trailing hyphens or dots.** Avoid `feature/new--login`, `feature/-new-login`, `feature/new-login-`, `release/v1.-2.0`. 3. **Clear and concise.** The name should describe the purpose without being verbose. 4. **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: ```bash 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.