GitHub branch naming convention
Table of content
If you're looking to create your own GitHub project or contribute to an existing one, understanding branch naming conventions is crucial. This guide will help you navigate and implement effective branch naming practices.
Branch Naming Convention
1. Standard Branch Naming Format
A commonly used branch naming convention follows this structure:
1<category>/<issue-number>-<short-description>
✅ Example:
1feat/123-add-login
2fix/456-bug-navbar
3hotfix/789-fix-crash
2. Common Branch Prefixes
| Prefix | Purpose |
|---|---|
| feat/ | New feature development |
| fix/ | Bug fixes |
| hotfix/ | Critical production fixes |
| chore/ | Maintenance tasks (e.g., updating dependencies) |
| refactor/ | Code improvements without changing functionality |
| test/ | Adding or updating tests |
| docs/ | Documentation updates |
| release/ | Preparing for a new release |
| ci/ | Changes related to CI/CD pipelines |
✅ Example:
1feat/432-add-dark-mode
2fix/567-login-error
3docs/update-readme
4release/1.2.0
3. Best Practices for Naming Branches
✅ Use lowercase letters and hyphens (-) for better readability.
✅ Include an issue/ticket number if using a tracker (e.g., JIRA, GitHub Issues).
✅ Keep branch names short yet descriptive.
✅ Use verbs in active voice (e.g., add-login, fix-navbar).
❌ Avoid Generic Names:
1bugfix
2feature1
3new-update
✅ Better Alternatives:
1fix/404-button-click
2feat/user-dashboard
4. Special Branches
| Branch Name | Purpose |
|---|---|
| main | The stable production-ready branch |
| develop | The main development branch |
| release/x.y.z | Used to prepare for releases |
| hotfix/x.y.z | Urgent fixes for production issues |
✅ Recommended Workflow:
1main → develop → feature branches → release → main
✅ Example Workflow in Action:
1git checkout -b feat/101-user-authentication
2git checkout -b fix/302-broken-signup-button
3git checkout -b hotfix/1.2.3-security-patch
5. Summary
✅ Use prefixes (feat/, fix/, hotfix/, etc.)
✅ Follow a clear pattern (
✅ Avoid generic names (feature1, update, fixbug)
✅ Use Git hooks to enforce naming conventions