OGG… What kind of Git branch naming convention is commonly used??

git branch
Author

Ryo Nakagami

Published

2025-09-14

Modified

2025-09-16

🔎 Objectives

  • Make branch purpose explicit, collaboration smoother, and automation possible.
  • Create clarity, consistency, and traceability in how teams manage code.

🎯 Goals

  • Define clear branch categories (feature, fix, release, etc.) with consistent tokens.
  • Ensure branch names immediately communicate intent.
  • Enable integration with issue trackers and CI/CD pipelines.
  • Reduce confusion by standardizing naming across the team.

📘 Guideline

① Use lowercase letters and hyphens to separate words

  • Branch names should always be lowercase for consistency and avoid conflicts in case-sensitive file systems.
  • Hyphens (-) make branch names easier to read than underscores or camelCase.

Example 1

  • ✅ Example: feat/user-login
  • ❌ Avoid: Feat_UserLogin, FeatUserLogin

② Start branch names with a clear token

  • Each branch should begin with a category token that defines its purpose.
  • Common tokens: feat (feature), fix (bug fix), docs (documentation).
  • Use slashes / to separate tokens and descriptions
  • This makes the branch purpose obvious at a glance.

Example 2

  • ✅ Example: fix/payment-timeout
  • ❌ Avoid: payment-timeout (purpose unclear)

This clarity is not only helpful for humans reading the branch list or PRs but also allows Git commands and CI/CD scripts to filter, map, or operate on specific branch types efficiently.

# Listing branches by token
git branch --list "feature/*"

# Pushing or mapping branches with tokens
git push origin 'refs/heads/feature/*'

# Deleting multiple branches by token
git branch -D $(git branch --list "feature/*")

③ Link to issues or tickets when possible

  • If your team uses Jira, GitHub Issues, or another tracker, include the ticket/issue ID.
  • This improves traceability between code, commits, and tasks.

Example 3

  • ✅ Example: feat/123-user-auth
  • ❌ Avoid: feat/user-auth (missing link to ticket)

④ Keep branch names short but descriptive

  • Balance brevity with clarity.
  • Avoid overly long names while still describing the intent.

Long branch names can be very helpful when browsing a list of branches, as they provide more context. However, they can clutter one-line logs, obscuring the visible part of the log.

Example 4

  • ✅ Example: refactor/api-headers
  • ❌ Too long: refactor/update-the-way-we-handle-request-headers-in-api

⑤ Maintain consistency across the team

  • All developers must follow the same convention.
  • Consistency improves collaboration and enables automation in CI/CD.
  • Document rules in CONTRIBUTING.md or your project wiki.

Example 5

  • ✅ Example: Everyone uses feat/* for features
  • ❌ Avoid: Mixing feature/*, feat/*, new/* (causes chaos)

Branch Naming Convention

Work Branches

Format Purpose / Goal
feature/<name> New feature development
bugfix/<name> Bug fix
refactor/<name> Restructuring code without behavior change
docs/<name> Documentation updates
test/<name> Testing-related work
enh/<name> Performance enhancements

Lifecycle branches

Format Purpose / Goal
release/<version> Preparing a release
hotfix/<name> Urgent production fix
sandbox/<name> Experimental or prototype work

References