How to Write Great git Branch Names
Even after working with git for a few years I am still left in awe sometimes at its capabilities. The ability for developers to work on different parts of the same project at the same time through the use of branches is amazing. While these branches can help boost productivity by allowing simultaneous progress, they can also lead to wasted time and thought if used without proper naming conventions.
If you thought variables were the only items that caused issues when named improperly, just try to work with a 10 dev team who all use different naming conventions to create feature branches. This can make searching for a branch a chore at best and a headache at worst. The key for good branch naming is saying only as much as you need to in a uniform way. In this article I will walk you through some best practices and strategies for writing purposeful and informative git branch names.
Before we jump into what a good name looks like, I will provide an example of my favorite convention:
Starting with the Goal
The first thing that developers will care about when working on our reviewing your code is the goal of the branch. What are you trying to do with this. Is this branch a full fledged feature, or a hot fix for a pressing production error? Is this a branch that focuses on creating or bolstering tests? What the goal is is very important and should be at the beginning of your branch name.
Which Team are You On?
If your company has many separate projects, or development divisions, then it is important to add another flag to help filter between teams. If you work on the storefront and your friend works in billing then it makes sense to add “ecomm” to your tickets and they can add ‘bill” to theirs. This helps differentiate the tickets and will help keep the ticket numbers reasonable and orderly.
Always Include Issue Numbers
Your tickets probably have numbers and your branch names should too! Yes, it is easy to link to Asana or Jira tickets from your PR, but wouldn’t it be nice to have the ticket number in your branch name as well? Don’t forget to put this number in to help users easily find the branches that they are supposed to review, add to or branch off of!
Using Hyphens, Slashes and Underlines
Another convention that will make your branches easier to follow is use of hyphens and slashes. Of course you could separate every word or set of numbers with a hyphen, a more robust pattern of hyphens, slashes and underlines will make your branches even easier to read. An example of a bad use of this is “feature-claims-45-fix-dead-link.” While all the information you need is there, it is not the easiest to read. Instead we could use something like “feature/claims-45_add-policy-comparison.” This pattern makes it clear to other devs that the branch is a feature for the claims unit of your business, it is the 45th ticket for this business and the intention is to add a policy comparison. Much better!
Keep it Brief
Though it’s tempting to write a very descriptive purpose for each of your branches, the more brief the better. While extra context can be necessary, if you already include the issue or ticket id then it is not necessary to type a novel.
To Name, or not to Name
Some companies advocate adding the author’s name to the branch name. I don’t recommend this for two reasons. First, if you are using Github then it should be easy enough to use the UI to filter for certain developer’s tickets. This filtering and searching make accountability simple through other means besides naming.
Second, prefixing all branches with someone’s name ruins consistent naming conventions. If you start with a name, then users will have to scan to find if a branch is a fix, feature, test or other. Along with this, longer names quickly clutter the ticket and take away the brevity of a clean naming.
Unless you have a very good reason, I would stay away from adding developer names to your branches. Less is more when improving readability and naming impact on your branch.
Final Thoughts
Reviewing code should never be a chore. Because of this it is important to make your git branch names as easy to read as possible. Let me know in the comments if you and your team use other conventions for branch naming!
Notes
https://codingsight.com/git-branching-naming-convention-best-practices/
