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
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
(user-id)is a user name such as
(short-description)is a phrase, such as
(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
- Not everyone likes the term
topicas 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
- Often team members accidently use
user, which results in duplicate folders in these tools. I typically advise to use the singular case as
bug, etc are all singular case as well.
- Case matters, so
featurewill 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.
Let me know what you think of this article on twitter @Erpenbeck!