Branch Naming Conventions
Consistent branch naming makes it easier to understand what's being worked on, automate workflows, and maintain a clean repository.
Why Naming Conventions?
Good names help with:
| Benefit | Example |
|---|---|
| Clarity | feature/user-auth vs stuff |
| Sorting | All features grouped together |
| Automation | CI can detect branch type |
| Communication | Team knows what's in progress |
| Cleanup | Easy to identify stale branches |
Common Naming Patterns
Type Prefixes
feature/ - New features
bugfix/ - Bug fixes
hotfix/ - Urgent production fixes
release/ - Release preparation
docs/ - Documentation
test/ - Test additions
refactor/ - Code refactoring
chore/ - Maintenance tasks
Full Format
<type>/<issue-id>-<short-description>
Examples:
feature/AUTH-123-add-login
bugfix/BUG-456-fix-redirect
hotfix/SEC-789-patch-vulnerability
docs/update-api-reference
Alternative Formats
# With username
alice/feature/user-auth
# With date
2025-01/feature/user-auth
# Just description (simpler teams)
add-user-authentication
Naming Rules
Use Lowercase
✅ feature/user-auth
❌ Feature/User-Auth
❌ FEATURE/USER-AUTH
Use Hyphens, Not Spaces or Underscores
✅ feature/user-authentication
❌ feature/user_authentication
❌ feature/user authentication (invalid)
Be Descriptive But Concise
✅ feature/add-user-login
❌ feature/f1 (too vague)
❌ feature/add-the-user-login-feature-that-allows-users-to-sign-in (too long)
Include Issue Reference
✅ feature/AUTH-123-add-login
✅ bugfix/issue-456-fix-null
Makes it easy to find related issues/PRs.
Type-Specific Guidelines
Feature Branches
feature/user-authentication
feature/AUTH-123-add-oauth
feature/shopping-cart
Purpose: New functionality
Bugfix Branches
bugfix/login-redirect-loop
bugfix/BUG-456-null-pointer
bugfix/fix-memory-leak
Purpose: Non-urgent bug fixes
Hotfix Branches
hotfix/security-patch
hotfix/SEC-789-xss-vulnerability
hotfix/critical-payment-bug
Purpose: Urgent production fixes
Release Branches
release/1.2.0
release/v2.0.0-beta
release/2025-q1
Purpose: Prepare for release
Documentation Branches
docs/api-reference
docs/update-readme
docs/add-contributing-guide
Purpose: Documentation only
Team Examples
Simple Team
main
feature/add-login
feature/shopping-cart
bugfix/fix-navbar
With Issue Tracking
main
develop
feature/JIRA-123-user-auth
feature/JIRA-456-cart
bugfix/JIRA-789-login-fix
With Usernames
main
alice/feature/user-auth
bob/bugfix/login-fix
carol/feature/checkout
Automation with Naming
Branch Protection
Protect based on patterns:
# GitHub branch protection
branches:
- main
- release/*
CI/CD Triggers
# GitHub Actions
on:
push:
branches:
- main
- 'feature/**'
- 'release/**'
jobs:
deploy-staging:
if: startsWith(github.ref, 'refs/heads/feature/')
# Deploy features to staging
deploy-production:
if: github.ref == 'refs/heads/main'
# Deploy main to production
Auto-labeling PRs
# Based on branch prefix
- head-branch: ^feature/
label: feature
- head-branch: ^bugfix/
label: bug
- head-branch: ^hotfix/
label: urgent
Long-Running Branches
Permanent Branches
main - Production code
develop - Integration branch
staging - Pre-production testing
Temporary Branches
feature/* - Short-lived (days)
bugfix/* - Short-lived (days)
release/* - Limited duration (weeks)
Branch Lifecycle
Creation
# Create with meaningful name
git checkout -b feature/AUTH-123-add-login
During Work
# Keep updated
git pull origin main
git rebase main # or merge
After Merge
# Delete locally
git branch -d feature/AUTH-123-add-login
# Delete remotely
git push origin --delete feature/AUTH-123-add-login
Viewing Branches
List by Pattern
# All feature branches
git branch --list 'feature/*'
# Remote features
git branch -r --list 'origin/feature/*'
Sort by Date
# Most recent first
git branch --sort=-committerdate
Common Mistakes
Too Vague
❌ fix
❌ update
❌ test
❌ my-branch
✅ bugfix/fix-login-validation
✅ feature/add-password-reset
Too Personal
❌ johns-stuff
❌ wip
❌ temp
✅ feature/TICKET-123-user-profile
No Convention
❌ Mixed styles in same repo:
Feature/add-login
bugfix_fix_logout
ADD-FEATURE
my feature branch
Documenting Conventions
Create a CONTRIBUTING.md with guidelines like:
Branch Naming Format:
type/ticket-id-description
Types:
feature/- New featuresbugfix/- Bug fixeshotfix/- Urgent fixesdocs/- Documentation
Examples:
feature/AUTH-123-add-oauthbugfix/BUG-456-fix-nulldocs/update-api-docs
Rules:
- Use lowercase
- Use hyphens (not underscores)
- Include ticket ID when available
Summary
- Use consistent prefixes (feature/, bugfix/, etc.)
- Use lowercase with hyphens
- Include issue/ticket references
- Keep names descriptive but concise
- Delete branches after merging
- Document conventions for team
- Leverage naming for automation
In the next lesson, we'll learn about keeping a clean Git history.
التالي · الدرس 40 من 40
Keeping History Clean
قراءة 4 دقيقة
أنهيت 39 من 40 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

