tomevault-io Git Branch Naming Conventions
Consistent branch naming improves traceability, enables automation, and makes repository history easier to navigate.
When to Use This Skill
| Use this skill when... | Use something else when... |
|---|---|
| Creating a new feature/fix branch | Managing PR workflows → git-branch-pr-workflow |
| Setting up team branch conventions | Committing changes → git-commit-workflow |
| Discussing naming standards | Rebase/merge strategies → git-branch-pr-workflow |
Branch Name Format
{type}/{issue}-{short-description}
| Component | Format | Required | Example |
|---|---|---|---|
type |
Lowercase prefix | Yes | feat, fix |
issue |
Issue number, no # |
If issue exists | 123 |
description |
kebab-case, 2-5 words | Yes | user-authentication |
Examples
# With issue number (preferred when issue exists)
feat/123-oauth-login
fix/456-null-pointer-crash
chore/789-update-dependencies
docs/101-api-reference
# Without issue number (when no issue exists)
feat/oauth-integration
fix/memory-leak-cleanup
chore/update-eslint-config
refactor/auth-service-split
Branch Types
| Type | Purpose | Conventional Commit |
|---|---|---|
feat/ |
New features, capabilities | feat: |
fix/ |
Bug fixes | fix: |
chore/ |
Maintenance, deps, config | chore: |
docs/ |
Documentation only | docs: |
refactor/ |
Code restructuring, no behavior change | refactor: |
test/ |
Adding/updating tests | test: |
ci/ |
CI/CD pipeline changes | ci: |
hotfix/ |
Emergency production fixes | fix: (with urgency) |
release/ |
Release preparation | chore: or release: |
Creating Branches
Standard Workflow
# With issue number
git switch -c feat/123-user-authentication
# Without issue number
git switch -c fix/login-timeout-handling
# From specific base
git switch -c feat/456-payment-api main
git switch -c hotfix/security-patch production
Validation Pattern
Before creating, validate the format:
# Branch name regex pattern
^(feat|fix|chore|docs|refactor|test|ci|hotfix|release)/([0-9]+-)?[a-z0-9]+(-[a-z0-9]+)*$
Valid:
feat/123-user-auth✓fix/memory-leak✓chore/update-deps✓
Invalid:
feature/user-auth✗ (usefeat, notfeature)fix/UserAuth✗ (use kebab-case, not PascalCase)my-branch✗ (missing type prefix)feat/fix_bug✗ (use hyphens, not underscores)
Issue Linking Best Practices
When to Include Issue Numbers
| Scenario | Include Issue? | Example |
|---|---|---|
| Work tracked in GitHub Issues | Yes | feat/123-add-oauth |
| Work tracked in external system (Jira, Linear) | Optional | feat/PROJ-456-oauth or feat/oauth |
| Exploratory/spike work | No | spike/auth-approaches |
| Quick fix without issue | No | fix/typo-readme |
| Dependabot/automated PRs | No | chore/bump-lodash |
External Ticket Systems
For Jira, Linear, or other systems, use the ticket ID:
feat/PROJ-123-user-dashboard
fix/LINEAR-456-api-timeout
chore/JIRA-789-update-sdk
Description Guidelines
Good Descriptions
| Pattern | Example | Why Good |
|---|---|---|
| Action + Target | add-oauth-login |
Clear what's being done |
| Component + Change | auth-service-refactor |
Identifies affected area |
| Bug + Context | null-pointer-user-save |
Describes the issue |
Avoid
| Anti-pattern | Problem | Better |
|---|---|---|
fix/bug |
Too vague | fix/123-login-validation |
feat/new-feature |
Meaningless | feat/user-dashboard |
feat/john-working-on-stuff |
Not descriptive | feat/456-payment-flow |
fix/issue-123 |
Redundant, no description | fix/123-timeout-error |
feat/add-new-user-authentication-system-with-oauth |
Too long | feat/oauth-authentication |
Length Guidelines
- Minimum: 2 words after type/issue (
feat/123-user-auth) - Maximum: 5 words, ~50 characters total
- Sweet spot: 3-4 words (
feat/123-oauth-token-refresh)
Special Branch Patterns
Release Branches
release/1.0.0
release/2.1.0-beta
release/v3.0.0-rc1
Hotfix Branches
hotfix/security-vulnerability
hotfix/critical-data-loss
hotfix/production-crash-fix
Long-Running Branches
For multi-week efforts, consider date suffix:
feat/123-major-refactor-2026q1
epic/new-billing-system
Team Conventions
User-Prefixed Branches (Optional)
For large teams where branch ownership matters:
# Pattern: {user}/{type}/{description}
alice/feat/123-oauth
bob/fix/456-memory-leak
# Or: {type}/{user}-{description}
feat/alice-oauth-integration
fix/bob-memory-leak
Protected Branch Patterns
Configure branch protection for:
main
master
develop
release/*
hotfix/*
Automation Integration
Branch Name → Commit Scope
The branch type can inform commit message scope:
| Branch | Suggested Commits |
|---|---|
feat/123-auth |
feat(auth): ... |
fix/456-api |
fix(api): ... |
docs/readme |
docs: ... |
CI/CD Triggers
Common patterns for CI pipeline triggers:
# GitHub Actions example
on:
push:
branches:
- 'feat/**'
- 'fix/**'
- 'hotfix/**'
pull_request:
branches:
- main
Quick Reference
Branch Creation Checklist
- Starts with valid type prefix (
feat/,fix/, etc.) - Issue number included (if tracked work)
- Description is kebab-case
- Description is 2-5 words
- Total length under 50 characters
- No underscores, spaces, or uppercase
Command Reference
| Action | Command |
|---|---|
| Create branch | git switch -c feat/123-description |
| List by type | git branch --list 'feat/*' |
| Delete local | git branch -d feat/123-description |
| Delete remote | git push origin --delete feat/123-description |
| Rename | git branch -m old-name new-name |
Type Selection Flowchart
Is it a bug fix? → fix/
Is it a new capability? → feat/
Is it documentation? → docs/
Is it maintenance/deps? → chore/
Is it restructuring code? → refactor/
Is it adding tests? → test/
Is it CI/CD changes? → ci/
Is it an emergency? → hotfix/
Converted and distributed by TomeVault — claim your Tome and manage your conversions.