Git Branching Naming Convention: Best Practices to Follow

Introduction

Branching in Git allows developers to work on multiple features or changes simultaneously without interfering with each other's work or changing the main codebase. As branches are essential to Git, some naming conventions have been adopted to maintain a clear and organized codebase.

Adhering to the best practices of branch naming is especially important when collaborating on a project since it eliminates confusion and keeps everyone's work consistent.

This article will tell you about different Git branch naming conventions and the best practices for an organized repository.

Git Branch Types

Branches in Git can be categorized into two types based on their longevity and the type of change they introduce:

• Regular branches.
• Temporary branches.

This categorization allows teams to manage their Git workflows better. Proper naming ensures that long-lived branches remain stable and that temporary branches are used for specific, short-term tasks without cluttering the repository's history.

The sections below explain the two types in detail.

Regular Git Branches

Regular branches in Git are long-lived branches that are a stable and structured way to organize ongoing work. Those branches are permanently available in the repository, and their naming is straightforward.

Some regular Git branches are:

• Master (master/main) branch. The default production branch in a Git repository that needs to be permanently stable. Developers can merge changes into the master branch only after code review and testing. All collaborators on a project must keep the master branch stable and updated.
• Development (dev) branch. The main development branch that serves as a central hub for developers to integrate new features, bug fixes, and other changes. Its primary purpose is to be the place for making changes to keep the developers from implementing them directly in the master branch. Developers test, review, and merge the changes from the dev into the master branch.
• QA (QA/test) branch. The branch that contains all the code ready for QA and automation testing. QA testing is necessary before implementing any change in the production environment to maintain a stable codebase.

Temporary Git Branches

Temporary branches are short-lived and disposable. Those branches serve specific, short-term purposes and are often deleted afterward.

Some of the temporary branches in Git are:

• Bugfix branch. The bugfix branch contains the code with bugs that require prompt fixes. It can be the rejected code from feature branches that needs fixing before implementation.
• Hotfix branch. The hotfix branch is a place for implementing a temporary solution into a buggy code without adhering to the usual procedure. The hotfix branch is used in an emergency and when a fast fix is needed. Developers merge the hotfix branch directly into the production branch and later into the development branch.
• Feature branch. A feature branch serves to add, reconfigure, or remove a feature. The feature branch is based on the development branch. After the changes are made, developers merge the feature branch back into the development branch.
• Experimental branch. This branch serves as a place for developing new features or ideas that are not part of a release or a sprint. It is a branch for trying out new things.
• WIP branch. Devs use WIP (work in progress) branches to develop or try out new features. These branches may not necessarily be part of the regular development workflow. WIP branches are project-specific and often informal, with no specific or standardized rules.
• Merging branch. A merging branch is a temporary branch used for resolving merge conflicts. Conflicts can arise when merging the latest development and a feature or hotfix branch into another branch. The merging branch is also useful when combining two branches of a feature developed by multiple contributors. This process involves merging, verifying, and finalizing the changes.

The list above is not comprehensive. There are many more recommended formats and naming conventions for temporary branches, which are project-specific.

The following diagram shows an example workflow in a Git repository with several regular and temporary branches:

Git Branching Naming Conventions

Many different branch naming conventions are usually project or team-specific. Use those that best suit your needs as long as the usage is consistent throughout the project.

Below are some basic naming conventions for Git branches many developers use in version control systems.

Using Hyphens and Slashes as Separators

One of the most common naming conventions is to use slashes (/) or hyphens (-) as separators in a branch name. The symbols make the branch name easier to read as you don't have to focus on discerning the words.

For example, compare the following branch names:

featurenewuserregistrationworkflowwithemailverification

and

feature/new-user-registration-workflow-with-email-verification

This branch name is descriptive and provides information about the branch's purpose, in this case, to add a new user registration workflow with email verification. However, it is much easier to discern its purpose when using separators, such as slashes and hyphens.

Additionally, shorten the branch name whenever possible. To make the one above even better, shorten it to:

feature/email-verification-workflow

Thus, the main advantages of using separators in a branch name are:

• Increased readability that prevents confusion.
• Facilitated management, especially when dealing with many branches.

Ensure the best readability by keeping branch names lowercase and separating the words with hyphens or slashes.

Using Numbers

If your business relies on Jira to create tickets for issues and develop new features, adding the ticket number to the branch name is helpful. The ticket number in a Git branch name helps keep track of the developer's progress when working on that branch. Additionally, Jira ticket numbers are unique, so there is no risk of two branches having the same name.

If you use an external system to track the development progress, specify an external tracking ID in the branch name. However, avoid using only numbers and give the branch a descriptive name to clarify its purpose.

For example, the following branch name contains a tracking ID as well as a description:

wip/8712-add-login-module

The branch is a work in progress, followed by a tracking ID and a description of its purpose.

Using Category Words

It is common practice to start the branch name using a category word that marks the purpose of the branch. The category words usually depict the branch type, such as:

• bugfix
• hotfix
• wip
• feature, etc.

Using categorization helps developers who work together on a project to understand the purpose of the branch. The category word is commonly separated from the rest of the branch name using a slash (/).

For example, the following branch name uses a category word at the start of the name to depict its purpose:

bugfix/fix-login-error

The aim of the branch is to fix the login error, and it is created only for that purpose.

Using Author Name

Another naming convention is to use the author's name in the Git branch name to clarify which developer has worked on the branch. That way, it is easy to track who works on a feature. The author's name is usually the first element of the branch name.

For example:

johndoe/feature/add-user-profile

In this example, the branch name begins with the author's name, followed by a forward slash that separates it from the branch type. Then comes the purpose of the branch, which is to add a user profile feature.

Name Length

Keep the branch names descriptive but as short and simple as possible, especially when collaborating on a project. Developers need to quickly identify what the branch is for by looking at the branch name.

For example, to improve the following branch name:

feature/user-authentication-system-with-two-factor-authentication

We can shorten it to:

feature/2fa-auth

Using branch names that are too long can make it difficult to tell branches apart, especially as the project becomes more complex and the branch number increases. Working with short, simple names is much easier.

Using Several Naming Conventions Together

It is possible to use several Git branch naming conventions simultaneously. However, avoid applying all the rules to name each branch. Instead, combine them in a natural and clear way to maintain readability. For example, consider the following branch name:

feature/user-registration-system/bugfix/T-133-issue123

This name has multiple naming conventions and indicates a feature branch for a user registration system, with a Jira ticket 133 for issue 123 bugfix.

Although descriptive, the name is quite long and difficult to work with. On the other hand, we can shorten it to:

feature/T-133-bugfix

This shortened name still provides the necessary context but is much easier to handle, with fewer naming conventions. Ultimately, it is up to your team to decide how much information to include in the names and stick to the convention. That way, you will ensure the repository remains organized and easy to manage.

Conclusion

Git is an excellent way for multiple developers to work on the same codebase. This article has listed the conventions you can use to name branches and provided the best practices you should follow to keep the codebase clean and organized.

Learn more about Git in our tutorial for Git branching strategies, or see how to Git push to a remote branch.