Chapter 4.4 — Branch Naming Conventions☕ 10 min read

Branch Naming Conventions

feat/ naya, fix/ bug, hotfix/ emergency. Ticket number zaroor daalo. Aur merge ke baad branch DELETE karo!

01The Prefix System: Type Se Pehchano

Branch names without prefixes are like files without extensions — you have to open them to know what they contain. A prefix instantly tells you the category of work.

The prefix system is a convention used by professional teams worldwide. The prefix is followed by a forward slash and then a short description:

feat/ — new feature (feat/user-authentication)
fix/ — bug fix (fix/login-null-crash)
chore/ — maintenance tasks (chore/update-dependencies)
hotfix/ — production emergency (hotfix/payment-timeout)
docs/ — documentation (docs/api-reference)
refactor/ — code restructuring (refactor/auth-module)
test/ — adding tests (test/auth-integration)
release/ — release preparation (release/2.1.0)

When you see fix/ in a branch list, you immediately know it is a bug fix. hotfix/ tells you production is on fire. No guessing, no asking "what does this branch do?"

# Good naming conventions
git checkout -b feat/JIRA-456-user-registration
git checkout -b fix/JIRA-789-login-null-pointer
git checkout -b chore/update-node-18
git checkout -b hotfix/payment-timeout
git checkout -b docs/api-reference

# List branches by prefix
git branch --list 'feat/*'
git branch --list 'fix/*'
git branch --list 'hotfix/*'

The prefix slash matters. Git treats feat/ as a directory separator. You can list all feature branches with git branch --list 'feat/*'. This is why the slash convention is not just cosmetic — it is a functional organization tool. Some Git GUI tools even group branches by prefix automatically.

02Ticket Numbers: Traceability Ka Raaz

A ticket number (like JIRA-123 or GH-456) in your branch name creates a direct link between code and context.

The format is simple: <type>/<TICKET-ID>-<short-description>

Example: feat/JIRA-456-user-auth — this tells you:

feat/ — it is a new feature
JIRA-456 — the Jira ticket for requirements and discussion
user-auth — what the feature does

Without a ticket number, branches are orphaned knowledge. Nobody can trace why the branch was created, what requirements it fulfills, or who requested it.

Some tools auto-link PRs to tickets when the ticket number appears in the branch name or PR title. GitHub will auto-close issues when you write "Fixes #123" in a commit message.

# With ticket numbers (BEST PRACTICE)
git checkout -b feat/JIRA-456-user-auth
git checkout -b fix/GH-789-login-crash
git checkout -b hotfix/JIRA-101-payment-failure

# GitHub auto-links PRs when ticket number is in title/branch
# "Fixes #123" in commit message auto-closes the issue!

# Bad: no ticket number
git checkout -b add-auth  # Which ticket? Why? Who asked for it?

💡 Pro Tip: If your team uses Jira, GitHub Issues, or Linear, always include the ticket ID. Tools like Jira can auto-detect branch names and link them to tickets. This creates an audit trail: ticket → branch → PR → merge. Future developers can trace every change back to its original requirement.

03Rules for Good Branch Names

Good branch names follow consistent rules. These are not just preferences — they are team agreements that make the repository navigable.

Use lowercase letters and hyphens — not underscores or camelCase. add-auth not add_auth or addAuth.
Keep it short but descriptive — under 50 characters. Long names get truncated in Git output.
Use imperative mood — add-auth not added-auth or adding-auth. Think of it as a command: "add authentication".
Do not use your name — johns-branch tells nothing about the code. Git already tracks who created the branch.
Do not use vague names — fix, update, test, wip are meaningless without context.
Be consistent — the whole team must follow the same convention. Document it in a CONTRIBUTING.md file.

# GOOD
feat/PROJ-123-add-user-auth
fix/PROJ-456-login-null-pointer
chore/update-to-node-18

# BAD
my-branch
fix
update
test123
johns-auth-work
final_final_v2
adding-new-feature

Imperative mood matches Git's own convention. Run git log and you will see Git generates messages like "Merge branch" not "Merged branch". Your branch names should follow the same pattern: "add-auth" not "added-auth". This consistency makes the repository feel professional and predictable.

04Anti-Patterns: Naam Se Pehchaan Mat

These are the branch names that haunt repositories. You have seen them. We have all seen them. Stop creating them.

my-branch — Whose? What does it do? Nobody knows.
fix — Fix what? There are a thousand bugs in the backlog.
update — Update what? Dependencies? Code? Documentation?
wip — Everything is work in progress. This tells you nothing.
test — Test what? Unit tests? Integration? Manual testing?
final_final_v2 — That is what version control is FOR. Stop embedding versions in branch names.
sahil-branch — Sahil does not own the branch. The team does. And Sahil left 3 months ago.

These names are technical debt from day one. Three weeks later, even the creator will not remember what "fix" was supposed to fix.

# Anti-patterns (NEVER DO THIS)
git checkout -b my-branch        # Whose? What?
git checkout -b fix              # Fix what?
git checkout -b update           # Update what?
git checkout -b wip              # Everything is WIP
git checkout -b test123          # Test what?
git checkout -b final-v2         # Don't embed versions in names
git checkout -b sahil-branch     # Names don't describe code

# If you see these in your repo, clean them up!
git branch --merged main | grep -v "main" | xargs git branch -d

The real cost of bad names: Imagine onboarding a new developer. They run git branch and see: fix, update, wip, my-branch. They have to ask someone what each branch does. Good names eliminate these questions entirely. A well-named repository is a well-documented repository.

05Bulk Branch Management

Over time, branches accumulate like dust. Old feature branches, abandoned experiments, merged branches that nobody deleted. This clutter makes git branch output useless.

Regular cleanup is a team discipline, not a one-time task:

List merged branches: git branch --merged main — these are safe to delete.
Delete local merged branches: git branch --merged main | grep -v "main" | xargs git branch -d
Prune remote references: git fetch --prune — removes stale remote-tracking branches.
GitHub auto-delete: Enable "Automatically delete head branches" in repository settings. This deletes the branch after PR merge.
Schedule monthly cleanup: Make it a habit. Put it on the calendar. Your future self will thank you.

# List branches older than 3 months
git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative)' refs/heads/ | grep "months ago"

# Delete all merged local branches (except main)
git branch --merged main | grep -v "main\|develop\|\*" | xargs git branch -d

# Delete stale remote branches older than 3 months
git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative)' refs/remotes/origin/ | grep "months ago" | awk '{print $1}' | xargs -I {} git push origin --delete {}

# GitHub: Auto-delete branch on merge
# Settings -> General -> Pull Requests -> "Automatically delete head branches"

💡 Pro Tip: Branches are temporary. Think of them like paper plates — use them, merge them, throw them away. The merge commit preserves all the history. The branch name has served its purpose. Keeping old branches around is like keeping used paper plates — it only creates clutter and confusion.

Lo kar liya — Key Points:

✅ Use prefixes to categorize branches: feat/, fix/, chore/, hotfix/, docs/, refactor/, test/
✅ Always include a ticket number for traceability: feat/JIRA-123-add-auth
✅ Use lowercase, hyphens, imperative mood, and keep names under 50 characters
✅ Never use vague names (fix, update, wip) or personal names (johns-branch)
✅ Clean up merged branches regularly: git branch --merged main | xargs git branch -d
✅ Enable GitHub's auto-delete head branches feature to prevent branch buildup

Previous4.3 — Trunk Based Development 📋 All Chapters Next Chapter4.5 — Stash Deep Dive →