What is the Best Git Branch Naming Convention?

1

git branch <category/reference/description-in-kebab-case>

A git branch should start with a category. Pick one of these: feature, bugfix, hotfix, or test.

  • feature is for adding, refactoring or removing a feature
  • bugfix is for fixing a bug
  • hotfix is for changing code with a temporary solution and/or without following the usual process (usually because of an emergency).
  • test is for experimenting outside of an issue/ticket
  • doc is for adding, changing or removing documentation

How to Include Issue References?

After the category, there should be a “/” followed by the reference of the issue/ticket/task you are working on. If there’s no reference, just add no-ref. With task it is meant as benchmarking task e.g. batch_integration.

How to Write a Branch Description?

After the reference, there should be another “/” followed by a description which sums up the purpose of this specific branch. This description should be short and “kebab-cased”.

By default, you can use the title of the issue/ticket you are working on. Just replace any special character by “-”.

What are Some Examples of Git Branch Names?

  • You need to add, refactor or remove a feature: git branch feature/issue-42/create-new-button-component
  • You need to fix a bug: git branch bugfix/issue-342/button-overlap-form-on-mobile
  • You need to fix a bug really fast (possibly with a temporary solution): git branch hotfix/no-ref/registration-form-not-working
  • You need to experiment outside of an issue/ticket: git branch test/no-ref/refactor-components-with-atomic-design

*Reference

How Do You Write an Effective Git Commit Message?

Type Use Case
feat Adding a new feature for the user.
fix Fixing a bug.
docs Documentation-only changes.
style Formatting, missing semi-colons; no code logic change.
refactor Code changes that neither fix a bug nor add a feature.
perf Changes that improve performance.
test Adding or correcting tests.
chore Routine tasks like updating dependencies or build tools.

Why Are Git Commit Messages So Important?

  • When you are applying for jobs, employers will look through your projects on GitHub and they will look through your commit history. Having good commits as a novice developer will help you stand out.

  • Having a good commit message history will allow you (or other developers working on your code) to quickly see what changes were made and why. This is useful if a bug is found in the code that needs to be fixed!

  • Having a good commit message history will also be helpful if you come back to a project you were working on after stepping away from it for a while. You likely won’t remember your thought process and changes made when initially writing out the code.

What is the Difference Between Bad and Good Commits?

When it comes to writing commits, it is crucial to know how to write them effectively. Here’s an example of a bad commit message:

1

fix a bug

Even though it describes what you did, the message is too vague, which leaves the other developers on your team confused. A good commit message will explain the why behind your changes. In other words, a commit message describes what problem your changes solve and how it solves them.

Effective commits consist of two separate parts: a subject, and a body:

Subject

A brief summary of the change you made to the project.

1

This is the change I made to the codebase
Note: Commit subject character limit GitHub has a 72-character limit, so we recommend keeping your commits’ subjects within this amount.

What Should Be in the Commit Message Body?

A concise yet clear description of what you did.

1

Describe the problem your commit solves and how.

Now that we learned the secret to creating a good commit message, let’s try and fix the commit message from earlier:

1
2
3

Add missing link and alt text to the company's logo

Screen readers won't read the images to users with disabilities without this information.

Ahh, that’s better! :) Now, developers can gain a better understanding of this commit message because it does the following:

  • Provides a subject that specifies your code’s action (e.g., “Add missing link and alt text to the company’s logo”).
  • Contains a body that provides a concise yet clear description of why the commit needed to be made (e.g., “Screen readers won’t read the images to users with disabilities without this information.”).
  • Separates the subject from the body with a new/blank line. This is a best practice we highly recommend following. It makes commit messages easier for other developers to read.

Some teams of developers might have their own convention for commit messages in specific formats. However, they still follow the same principles as this lesson outlined.

How Do You Commit with a Subject and Body?

Up until now, you’ve been told to commit with git commit -m <message>. To make a commit with subject and body in message, the simplest way is to type git commit without the -m flag and message argument.

When Should You Make a Git Commit?

A good way to view a commit is like a “snapshot” of your code at the moment that it was made. That version of your code up to that point will be saved for you to revert back to or look back at.

When writing code, it’s considered best practice to commit every time you have a meaningful change in the code. This will create a timeline of your progress and show that your finished code didn’t appear out of nowhere.

In other words, make a commit if you get a piece of code you are working on to function like you want it to, fix a typo, or fix a bug. As you gain experience, you will develop a better feel for what should be committed!

There will come a time when you are working on a project and you FINALLY get something just right (this would be a good time to commit), and then maybe 30 seconds to a few days later it breaks. You have no idea what you changed, everything looks to be the same and you don’t remember editing that line, but alas, it isn’t working how you want it anymore. You’d be able to go back through your commit history and either revert your code back to the last commit you made when you first got that part working or go back and see what your code looked like at that point in time.

*Reference