Git Branch Name Convention: Best Practices

Git branch naming conventions are agreed-upon patterns for naming branches in a repository, and the most common approach is to use a short, descriptive type prefix followed by a slash and a concise identifier, such as feature/login-page or bugfix/issue-1234. This article explains why conventions matter, how to structure names, and what to avoid, so you can pick a consistent system that works for your team.

Why Use a Branch Naming Convention?

Without a naming convention, branches quickly become a mess of fix, test, new-feature, and asdf. A clear convention makes it easy to:

• Identify the purpose of a branch at a glance (feature, bugfix, hotfix, etc.).
• Find related work by searching for a ticket ID or feature name.
• Automate workflows – CI/CD pipelines can trigger different actions based on the branch prefix.
• Clean up stale branches more confidently, knowing what each one was for.

Common Prefixes and Their Meaning

Most teams adopt a set of standard prefixes. Here are the most common ones:

• feature/ – new functionality or enhancements
• bugfix/ – fixing a bug (often used for non-critical issues)
• hotfix/ – urgent fix for a production issue
• release/ – preparing a new release (e.g., release/1.2.0)
• docs/ – documentation changes
• refactor/ – code restructuring without changing behavior
• test/ – adding or updating tests

How to Structure a Branch Name

A good branch name usually follows this pattern:

prefix/description

For example:

• feature/user-authentication
• bugfix/issue-1234
• hotfix/security-patch

When using an issue tracker, include the ticket ID to make linking automatic:

• feature/JIRA-456/checkout-page
• bugfix/GH-789/fix-button-alignment

Rules and Recommendations

While different teams have different preferences, these rules are widely accepted:

• Use lowercase – Git is case-sensitive, so Feature/Login and feature/login are different branches.
• Use hyphens or slashes to separate words – avoid spaces, underscores, and dots (dots can be ambiguous with file extensions).
• Keep it short – aim for 2-4 words after the prefix, not a full sentence.
• Be descriptive – feature/add-login is better than feature/new-stuff.
• Avoid trailing slashes and empty prefixes.

Common Mistakes to Avoid

Here are the most frequent pitfalls when naming branches:

• Using vague names like fix or update – they don’t tell you what is being fixed or updated.
• Mixing cases – Feature/Login and feature/login will confuse your team.
• Using only a ticket ID – 1234 is meaningless without context; prefer bugfix/1234 or feature/1234.
• Including personal names – johns-branch doesn’t describe the work.
• Using special characters like @, !, or # – they can break scripts and tools.

How to Choose a Convention for Your Team

If you’re starting from scratch, here’s a simple process:

1. Check your existing tools – if you use Jira, GitHub, GitLab, or Bitbucket, see if they suggest a format.
2. Start with the common prefixes – feature, bugfix, hotfix, release, docs, refactor.
3. Decide on separators – most teams use a slash after the prefix and hyphens between words.
4. Write a short README or CONTRIBUTING section documenting the convention.
5. Be consistent – enforce it in code reviews and CI checks.

Frequently Asked Questions

Should I use underscores or hyphens in branch names?

Hyphens are more common and are the default in most style guides. Underscores work but can be harder to type and are sometimes treated differently by tools. Use hyphens for word separation.

Can I include a slash in a branch name?

Yes, slashes are allowed and are used to create a hierarchical structure, like feature/login. However, you cannot have a branch name that ends with a slash or contains two consecutive slashes.

What is the difference between bugfix and hotfix?

A bugfix is a regular fix for a bug in development or testing, while a hotfix is an urgent fix for a critical issue in production that needs to be deployed immediately.

Should I include the ticket number in the branch name?

It’s a good practice because it links the branch to the issue tracker. Use the format prefix/ISSUE-ID/description, for example bugfix/PROJ-123/fix-login-error.

Can I use uppercase letters in branch names?

Technically yes, but it’s discouraged because Git is case-sensitive and it can lead to confusion. Stick to lowercase for consistency.

What if my team already has a different convention?

Consistency matters more than the specific rules. If your team has a working convention, keep it. If not, adopt one of the common patterns and document it.

Related

• Keep AI Agents Running Reliably in the Cloud
• Nvidia Shield TV 4K HDR Setup Guide
• Email Suppression Lists in Node.js: A How-To