Git Branch Naming Conventions

When you first start using git, it can be intoxicating to see how easily you can create new branches and merge them. You feel powerful – as if you can do whatever you want and git will keep track of everything for you. And it’s true! Using git for software development gives you a level of freedom that would be unimaginable without a version control system. But that very power can lead you astray. Without discipline, you’ll soon find yourself swimming in git branch names like “temp” or “fix”, even numbered names like “temp1”, “temp2” etc. To keep things straight, it helps to impose limits on yourself and adopt some git branch naming conventions.

It’s bad enough if you’re working by yourself, but when you’re collaborating with a team, maintaining discipline in naming branches is not optional. You need a system so that branches created by one person can be easily understood by everyone else in the team. This is particularly important for long-running projects where people move in and out over a period that could span years.

So here is a breakdown of the most common git branch naming conventions, how they’re used, and what informal organizations work together to develop these standards.

Splitting Git Branch Names into Tree-Like Structures

The git branch convention is to adopt a segmented approach to naming. So a typical git branch will be composed of 2 or 3 parts, each of which indicates the kind of feature we’re working on, starting at the broadest level, and moving down to the specific.

So the git branch name will look like this:

feature/user-login

The first part of the branch name indicates the kind of branch it is. For example:

1. Feature
2. Bugfix
3. Experimental
4. Hotfix
5. Ticket

And so forth.

The second part of the git branch name will provide finer details about what it is. In the above example, the name makes it clear that the branch is working on the “user-login” feature.

Spaces are Not Allowed, So We Use Hyphens

Since we’re not allowed to use spaces in git names, we use hyphens to separate parts of the name. For example:

ticket/123-adjust-volume-control

In this example, the first part of the git branch name makes it clear that we’re talking about a ticket, and “123” could be the ticket number, which in turn, relates to the volume control adjuster. So we’ve used hyphens to split the second part of the ticket into its components. How much detail to include depends on the organization. Technically, there’s no reason to include the name of the ticket in addition to the number, since presumably, that information is in a database somewhere. Still, practically, it can help to see at a glance what a particular branch is about.

Using Lowercase

By convention, we use lowercase in git for everything and all branches.

Name Initials for Personal Branches

Sometimes a developer might want to work on something related to a project that doesn’t immediately impact the whole team. In such situations, it’s common to use the initials of the person as the first item in the branch. For example:

js/rework-login-page

Here, “J and S” are the initials of the person who’s working on the branch. It’s important to note that there should be a clear list of top branches, otherwise, you risk “JS” as being interpreted as “JavaScript”, or something else. If a top-level name isn’t “fix” or “release”, or a set number of things, then we can assume that anything else is the initials of the person.

No Generic Names

While it might be tempting to quickly use a name like “temp” for a quick and dirty branch, such temptations must be resisted, especially in larger teams. While it’s easy to create a new branch and call it “temp”, while you think that you’re only going to work on it for a short while, you must remember that others can see it, and someone else might get confused about what “temp” is, since they may have created their own temp folder in the past!

The same goes for other generic names like “fix” or “hotfix”. These terms are fine if you’re the only developer on the team, but as soon as you use git as a collaboration tool, you have to adhere to naming conventions even in the short term. Discipline is key.

Who Decides Git Branch Naming Conventions?

Since git is a free and open-source version control system, no formal organizations develop rules. It’s entirely community-based. If you want, git will allow you to name your branches in any way you want. It’s just that the practices outlined above are shown to work in large teams. Also important, is the need for standardization if you work on open-source projects yourself. If you’re going to allow the public to contribute code to your project, then the naming standards of git take on even greater importance.

GitHub is a Major Influence

It’s for this reason, that git implementation platforms like GitHub have their own branch-naming conventions, and these conventions end up influencing the broader community. While GitHub itself doesn’t enforce any branch naming conventions, it has tools that allow project administrators to enforce naming conventions.

Administrators can use the GitHub project settings to create “branch protection rules”, which allow you to specify the kinds of names users are allowed to create for their branches. The syntax allows you to use wildcards to specify the naming convention. Let’s say I want to enforce a rule that branch names can only start with one of the following:

1. feature/
2. fix/
3. hotfix/
4. release/

The syntax for enforcing the above would be:

feature/*
fix/* 
hotfix/*
release/*

You can find the specific rules of the syntax in the fnmatch documentation.

Online Forums Discuss Git Branch Naming Convention Rules

Online forums on StackOverflow and Reddit are also brimming with discussions on git branch naming conventions, with opinions ranging from none, to ultra-strict. Through all the mess, though, certain conventions like the ones outlined above have come to be generally accepted, and it’s best that you follow at least the basic conventions, if not the more advanced ones.

Fine Line Between Complexity and Simplicity

Sometimes you’ll see people create git branch names that are overly long and descriptive. While it’s true that the purpose of branch naming conventions is to allow users to immediately know the purpose of the branch, you can take this too far by creating overly long descriptions like this:

feature/user-profile-interface-update-for-enhanced-user-experience-based-on-feedback

While the above is certainly descriptive, it goes too far. Even considerations like having the name wrap onto a newline are not as trivial as they may appear, since they interrupt the ability to easily scan a list of branches. Instead, something like the one below is better:

feature/user-profile-update

There’s a fine line between too descriptive and not descriptive enough. Try to use your judgment to find the sweet spot.

Git Branch Name Integration with Tools

Another reason for git branch naming conventions is that automated tools can take certain actions based on the name. For example, the system can automatically link branch names with issue tracking numbers, or automatically stage a branch that starts with “release/”. All these, and more, are ways to smoothen the development process, and they all rely on a standard git branch naming convention.

So don’t take the matter too lightly! Even if you’re a single developer, it’s good to get into the habit of properly naming your branches so that the habit carries over into a new environment where you need to work with others.