Let the branch name do all the talking in git

I like and use BEM for CSS, it clearly says all about the code and saves time for developers. And I badly wanted something for git as well. I don’t generally delete all the merged branches, I keep some branches which have huge or major code changes/enhancements. So when I look back at them after some time I want to understand what I did in that branch long ago. I am lazy to go through the code or commit message and want my branch name do the story telling about the work I did in that branch.

I tried googling but had the other idea. I work for HappyFox Chat and We have some of the top class developers here. So I took a paper and pen and started asking questions(even stupid ones 😁) that I had regarding the naming conventions and the best practices they follow. And guess what? now I have a better naming convention that anyone can understand and I suggest trying it if you are a beginner to git.

A typical branch name looks like this —

reason__details--tag

Looks like BEM right? Yes, because I don’t want to create a new pattern with / or () I just want to use the pattern or structure am familiar with, thus it looks like BEM.

pattern is divided into 3 parts : reason, details and tag. At max a Branch name can have at 4 words, but not more than that.

reason:

You might branch because of the following reasons and use them in the name:

1. New feature / New page
2. Content Changes
3. Fix / Hot-fix / Patch
4. Enhancement / Optimisation
5. Refactor
6. Delete / Remove / Undo
7. Update / Upgrade

Reason — label must be identical to the purpose of the branch. Try to have a single word in most cases and in extreme cases use - to separate multiple words.

Examples:

1. Branch for a new page or feature — page__page-details or feature__feature-details
2. For a Fix or a Patch — fix-123__fix-details or patch__patch-details . fix or patch can have a GitHub(or any other service) issue id with it
3. For Deleting — delete__branch-details or remove__branch-details

details:

A two or three short-word descriptions about the branch. Try not to go beyond three words, as you may end up having long branch name. Use three words only if you don’t have the need of using tag name.

Avoid long descriptive names for branches. They are branch names, not news headlines. Make them as short and descriptive as possible. It is always possible to cutdown the branch name to the specifics not to make it a long-named branch.

Examples:

1. Branch for a new page or feature — page__private-policy or feature__public-api
2. For a Fix or a Patch — fix-123__signup-routing or patch__file-uploader
3. For Deleting — delete__duplicate-images or remove__analytics-tracking

tag:

It is optional and can be used under special circumstances, like :

1. if you use any external tracker like pivotal and want to add its tracking id to it. or
2. any other extra details you want to add to your branch.

Use only one-word description for this.

Examples:

1. Branch for a new page or feature — page__private-policy--12345678 or feature__public-api--v2
2. For a Fix or a Patch — fix-123__signup-routing--recurring or patch__file-uploader--pdf

Thanks for reading my post. I’d like to hear your thoughts in comments. If you like the article, please click the💚 below so that more people may read it.