Organizing git branches with naming conventions

An opinionated convention for branches

The forward slash is a little known trick for developers that are new to git. Instead of using a dash or underscore, the forward slash gets interpreted by many IDEs and git tools as a directory structure. This creates a very nice grouping.

As an example, creating a branch named feature/647-update-radio-button rather than something like feature-647-update-radio-button will result in better organization within your git tools. Notice in the pictures below how the grouping makes the repo look different with the forward slashes.

Slashes in git branch names result in better organized naming convention

Example of a typical git repo without a convention

Most git client tools like GitKraken, Atlassian SourceTree, Visual Studio, etc parse the branch name and convert them into a nice folder structure.

An example with Atlassian SourceTree

Visual Studio also recognizes this convention

Table of branch types

While I use kebab-case, meaning it is all lower case with zero or more dash separators, in this convention, feel free to use whatever style that you prefer, such as PascalCase camelCase, etc. The convention for the wording between the slashes should be determined by the team’s preferences.

Definition of terms in the above table

• (id) is a work item id for a bug, user story, task, etc. For example 123.
• (user-id) is a user name such as merpenbeck.
• (short-description) is a phrase, such as recursive-loop-fix.
• (release-id) is a release identifier such as a semantic version number or date based.

Branch prefix support within git workflow tools

Beyond git UI clients, this convention is also built directly into the branch prefixes for some git workflows like gitflow.

Notice that if you plan to use gitflow, you may want to use bugfix rather than bug, but you can also configure gitflow to use the bug branch prefix instead.

Source code repository support

Hosted source code repositories, such as Azure DevOps Repos, have built-in support for the branch prefixes:

Additionally, tools like Bitbucket allow you to create branches with a branch prefix.

And filtering by branch prefix is also enabled based on the gitflow workflow.

Some places where teams have issues

1. Not everyone likes the term topic as a generalized way of referring to a bug or a feature, but it does make things a bit simpler. Decide as a team how you want to approach topic branches.
2. Often team members accidently use users rather than user, which results in duplicate folders in these tools. I typically advise to use the singular case as feature, bug, etc are all singular case as well.
3. Case matters, so Feature and feature will similarly result in duplicate folders. This comes down to being disciplined on naming and using scripting for building branches where you can.

I hope that this will help in organizing your git repos.