Conventional Branch
Create Git branches that follow the Conventional Branch specification — a simple, consistent convention for naming Git branches.
Branch Name Format
<type>/<description>
Branch Types
Purpose prefixes — describe the intent of the work:
AI agent source prefixes — identify branches generated by AI coding agents:
Use a vendor-specific prefix when you know which agent is producing the branch; use ai/ as a vendor-neutral fallback.
Trunk Branches
main, master, and develop are trunk branches — they do not use a prefix. Never create new branches with the same names as trunk branches; branch off them instead.
Naming Rules
- Lowercase only — no uppercase letters anywhere
- Alphanumerics, hyphens, and dots —
a-z, 0-9, -, .
- Dots are allowed in any description, typically for version numbers (e.g.,
release/v1.2.0, chore/upgrade-node-v20.11)
- No underscores, spaces, or special characters
- No consecutive hyphens (
--), dots (..), or hyphen-dot adjacency (-. or .-)
- No leading or trailing hyphens or dots in the description
Valid Examples
main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login
ai/refactor-auth-flow
copilot/add-login-page
cursor/fix-header-bug
claude/security-patch
codex/optimize-query
Invalid Examples
Description Guidelines
- Use kebab-case with 2-5 words
- Be descriptive but concise (~50 chars total)
- Good:
add-oauth-login, fix-header-overflow, update-ci-config
- Bad:
fix-bug, new-feature
Workflow
Follow these steps:
Step 1 — Determine Branch Type
Ask the user (if not already clear):
- Branch type — default to
feature when uncertain
- Brief description — what the branch is for
If the user mentions a ticket or issue number, include it in the description (e.g., feature/issue-123-add-oauth).
Step 2 — Validate the Name
Check the assembled name against the Naming Rules above. If any rule fails, fix it:
- Lowercase everything
- Replace underscores and spaces with hyphens
- Collapse consecutive hyphens
- Strip leading/trailing hyphens
Step 3 — Detect the Base Branch
Different repos use different trunk branches. Detect which one this repo uses:
# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'
If that returns nothing, check which trunk branch exists locally (priority order: develop, main, master):
for b in develop main master; do
git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done
Step 4 — Create and Checkout
git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>
Step 5 — Confirm
Tell the user:
- The branch name that was created
- That they are now on the new branch
- Remind them:
git push -u origin <branch-name> when ready
Validation
commit-check validates branch names against the specification. Run commit-check --branch, use its check-branch pre-commit hook, or commit-check-action in GitHub Actions. Configuration for GitHub rulesets, GitLab, Bitbucket and Git hooks is at https://conventionalbranch.org/enforce/.
Relationship with Conventional Commits
Conventional Branch complements Conventional Commits:
Align the branch type with commit types where possible (e.g., feature/* branches with feat: commits).