Git Good: Best Practices for Branch Naming and Commit Messages

Hello devs, I'm going to share a few best practices for using Git more effectively. git? Yes, the git you're already familiar with. The code buddy, your guardian angel that ensures your coding adventure runs smoothly, allows developers to collaborate effortlessly on projects.

Are you the one who creates branches and then forgets why they exist? The one always have to look for file changes to comprehend a commit? Here are some tips for you.

Why should I follow the standards?

• Clarity and Understanding

• Collaboration and Teamwork

• Ease of Navigation and Maintenance

• Documentation and Knowledge Transfer

• Project Quality

• Automated Changelogs

• Optimizing CI/CD

Before You Read

• Each seb-section under Branch Naming Conventions and Commit Message Conventions are ordered as basic, intermediate and advanced rules respectively.

• You can follow upto any level of rules based on use case and relevance, anyways following conventions upto intermediate rules level is recommended.

• Following contents are adapted and organised from resources provided in the reference section.

---

Branch Naming Conventions

Basics

1. Descriptive Names: A well-named branch gives immediate context for its purpose. Instead of generic names, choose clarity.
   For example: feature/login, bugfix/navbar-overflow

2. Use Hyphens: Use hyphens to seperate words (or kebab case) in branch name, this ensures readability.
   For instance, bugfix/fix-login-issue is more readable than bugfix/fixLoginIssue or bugfix/fix_login_issue.

3. Alphanumeric Lowercase Characters: Use only alphanumeric lowercase characters (a-z, 0–9) and hyphens. Avoid punctuation, spaces, underscores, or any special characters whenever possible.

4. Avoid Unneccessary Hyphens: Avoid unneccessary hyphens, like subsequent or trailing hyphens.
   For instance, feat/new--login- is a bad practice.

5. Short and Effective: Keep branch names simple. While descriptive, they should also be concise enough to convey the goal at a glance.

Prefix or Type

• Prefixing branches helps to organize them according to their purpose. This not only improves clarity, but also helps to automate workflows.

• Some of the common branch type prefixes and their usage cases include:

  • feature/: For developing new features,
  • bugfix/: To fix bugs in the code. Often created associated to an issue.
  • hotfix/: To fix critical bugs in the production.
  • release/: To prepare a new release, typically used to do tasks such as last touches and revisions.
  • docs/: Used to write, modify or correct documentation.

• For example, feature/new-feature or release/version-1.0.0.

Including Ticket Numbers

If your project employs an issue tracking system such as Jira, or if it revises based on github issues or another comparable tool. Including the token for the issue in the branch name would make it simple to track. Example: feature/PROJ-123-footer-links

---

Commit Message Conventions

• Final format for a commit message:

  <type>([optional scope]): <description>  # subject

  [optional body]

  [optional footer(s)]

Message Subject

• Imperative Mood: Create commit messages in the imperative mood. Start with a verb to indicate what the commit does.
  For example: Use fix: Fix bug #67 than fix: Fixed bug #67

• Short and Summarized: Try to fit the subject line inside 50 characters to ensure that messages are readable in various Git tools, such as when using git log --oneline. Avoid trailing period and unneccessary words/symbols.

• Capitalize the description: This is as easy as it sounds. Start subject line with a capital letter.

Type and Message Body

• A type preifx in the subject line can be used to represent type of the changes included in the commit. Some of the commonly used types are:

  • feat:: To summarize a new feature in the codebase.
  • fix:: To address a fix to the codebase.
  • build:, chore:, ci:, style:, refactor: are some other examples.

• A scope can be added to a commit's type to offer additional contextual information, and it is enclosed in parenthesis, for example, feat(parser): Add the ability to parse arrays

• A body can be added to the message to include detailed explanations in the commit.

• Body is added by leaving a blank line after the subject line.

• Wrap the body at 72 characters, ie. Use multple lines of body, where each line does not exceed 72 characters.

Footer and Extended Message Body

• A footer is use to convey addiotional information regarding the commit, such as reviewed by, approved by, etc. Example:

  • Signed-off-by: Alice <[e-mail]>

• Breaking Change: A BREAKING CHANGE refers to rather important major changes in the codebase. It can represented by adding a ! after type/scope and/or by adding it with body or as footer
  
  

  chore!: drop support for Node 6

  BREAKING CHANGE: use JavaScript features not available in Node 6.

• Multi-paragraph Body: In some circumstances, numerous paragraphs help to explain the goal of the commit in greater detail. Example: To describe what, why, and how, about a commit changes.

Examples

Various use case examples of commit messages may be found here.

Conclusion

Adhering to Git conventions is similar to speaking a common language. However, it is obvious that these standards or conventions are not enforced by any system; hence, the adaptation and extension of use of these standards is entirely up to us.

Embracing these habits will surely improve your Git experience and encourage a collaborative coding environment. Even though we can't follow these in a single blow, gradually adapting to them will undoubtedly make a difference.

I'm planning to write about Implementing Git Conventions with Husky, show your support with reactions and comments. Happy coding!

References

• Naming conventions for Git Branches — a Cheatsheet, by Abhay Amin

• Conventional Commits

• Git conventions

• How to Write a Git Commit Message by CBEAMS

• Git trailers

Thumbnail Photo by Yancy Min on Unsplash

Comments

[Zohar Peled]

When working in a team with multiple developers on the same project, I find it best to also include your first name on the branch name itself - assuming at any given point of time there are at least 4-10 active branches (depending on the size of the team and product), it really helps a lot to find it. My personal favorite convention: <FirstName>_<TaskNumber>_shorten-task-name - so Zohar_12345_Do-something

[shinjith]

Couldn't agree more! When I worked on complex web projects, there were typically a dozen or so branches created by different team members for various interfaces and other things. I used to include a short alias for myself at the end of a branch name.

[Ndeye Fatou Diop]

Same here! I generally do « nfdiop/branch-name »

[William Pursell]

The notion of embedding metadata about the commit in the subject (ie "conventional commits") is misguided. Rather than putting such data in the subject line, stash it in a trailer. wrp.github.io/blog/2024/01/03/conv...

[shinjith]

The notion of embedding metadata about the commit in the subject (ie "conventional commits") is misguided.

I don't think so; as I indicated in the conclusion, the conventional commit is not an obligatory practice; you can follow it in any way/extent you feel comfortable. If you are concerned about keeping consistency, I believe that is a small price to pay. The benefits of clean, organized commit histories and automated, rich changelogs and much more, feels significant to me.

Rather than putting such data in the subject line, stash it in a trailer.

Conventional commit already encourages including thorough explanation in the commit message body; formatting that is also a smart choice to match requirements like the tools you're talking about.

In the end, it's only individual or organizational choice to conform to such standards, and I never thought these conventions were mistaken or unnecessary.

[William Pursell]

I think you may be missing my point. I agree whole-heartedly that a clean, organized commit history is a desirable goal. Indeed, that is the entire reason that I discourage the practice of including meta-data in the subject line and instead encourage people to put that data in commit trailers. When projects attempt to place meta-data in the subject line, the formatting will inevitably be inconsistent.
By placing that data in trailers instead, there is some support from the tooling to ensure consistency and you gain a great deal of flexibility in viewing the data.

[shinjith]

I apologize for misinterpreting your message. I appreciate that you are recommending a better technique than adding all meta data in the subject line; that is true. I believe we should introduce a modern or better approach to do this with solid reasoning, as many people still follow traditional methods.

[HeetVekariya]

Great work !
My commit messages:

[shinjith]

Looks great! Were you able to do it consistently?

[HeetVekariya]

Well i enjoy writing good commit messages, and i am consistent from last HacktoberFest.

[Oscar]

This is a really informative post! I've just recently gotten in the habit of naming my branches correctly, but I didn't realize there were conventions for it.

[shinjith]

I'm glad you found it informative, and I'll attempt to do a follow-up on this.

[Adaptive Shield Matrix]

How about Subject-First Commit Messages?
github.com/aaronjensen/software-de...

[shinjith]

That is an interesting approach. This method is preferable when someone quickly checks the commit log for immediate information. Also, I believe it is preferable to put the type of commit as a prefix so that commits may be categorized with certain scripts or tools.

Anyway, it is a nice approach to describe, rather than lazy, on-the-go descriptions in the subject line.

[Adaptive Shield Matrix]

Every git tool in existance (gitlens, vscode, Github, Jetbrains, etc) only displays the first line of a git commit message. There are some esoteric git options to show more but in practice nearly no one bothers to use and remember them.
Very rarely do you go through all the git commit text.

Being able to quickly summary that the commit is about is much more valuable. If you want to you can still include tags for automated ci, ticket number or a description afterwards.

Summary: subject first approach is the best one.

[shinjith]

Agreed. Subject-first practice is a smart technique. I read in many places that a commit description should be able to complete this sentence:

If applied, this commit will your subject line here

I believe this is one of the reasons to use imperative mood in description.

Since you stated this, I also think subject-first is better; perhaps we should renovate these practices.

[dikamilo]

Branch names: ticket ids with mix of git flow
Commit messages: conventional commits with descriptive messages - "Fix bug #67" means nothing and have zero value if you want to generate changelogs.

[shinjith]

Sorry if you didn't find it useful! Maybe there are projects where this approach might help, such as for a project for tools that used by developers, in such cases referring issue number is enough or in similar situations.

[Paul Contreras]

This post is so good for improve our practices! cool

[shinjith]

Thank for you appreciation!

[Ritik Banger]

How to write Git commit messages like a Pro!

Ritik Banger ・ Oct 10 '22

#git #github #webdev #tutorial

[shinjith]

Great post!

[João Angelo]

Hi Shinjith ! Thanks for sharing

[shinjith]

You're welcome! I'm glad you found the post interesting.

[Aziz]

I enjoyed this read and do agree that your points are effective disciplines for beginner and veteran developers to practice.

[shinjith]

I'm glad you found this post informative and helpful!

[Dawit Beyene]

you got some typos in there buddy

[shinjith]

Loll! Too lazy to fix them, thought everyone would ignore :/. But atleast we can confirm this isn't AI generated

[Daniel Hillmann]

It's interesting you recommend inducing ticket number, e.g. for Jira, as to me it provides absolutely no value for the branch name (and browsing those). Tracking the issue is not limited to be included in the branch name; it can just be included in a commit message, the PR title or the PR description.

When going through branch names, who will find any value of something like feature/SHOP-123 or get a clue of the branch's purpose?

[shinjith]

Like I mentioned, I merely adapted & organised information from different references. I didn't try that approach where we use the ticket number like you said.

But maybe this is applicable to some project with strict handling of errors/bugs or so. I believe there might be some use cases for the same. I'm sorry if you didn't find it useful.