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
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
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 thanbugfix/fixLoginIssue
orbugfix/fix_login_issue
.Alphanumeric Lowercase Characters: Use only alphanumeric lowercase characters (a-z, 0–9) and hyphens. Avoid punctuation, spaces, underscores, or any special characters whenever possible.
Avoid Unneccessary Hyphens: Avoid unneccessary hyphens, like subsequent or trailing hyphens.
For instance,feat/new--login-
is a bad practice.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
orrelease/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: Usefix: Fix bug #67
thanfix: 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 <alice@example.com>
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 withbody
or asfooter
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!
Top comments (34)
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-somethingCouldn'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.
Same here! I generally do « nfdiop/branch-name »
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...
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.
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.
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.
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.
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.
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.
Great work !
My commit messages:
Looks great! Were you able to do it consistently?
Well i enjoy writing good commit messages, and i am consistent from last HacktoberFest.
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.
I'm glad you found it informative, and I'll attempt to do a follow-up on this.
How about Subject-First Commit Messages?
github.com/aaronjensen/software-de...
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.
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.
Agreed. Subject-first practice is a smart technique. I read in many places that a commit description should be able to complete this sentence:
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.
This post is so good for improve our practices!
cool
Thank for you appreciation!
How to write Git commit messages like a Pro!
Ritik Banger ・ Oct 10 '22
Great post!
Man if not this article, I would have kept my very bad naming conventions, which are mostly generic
Happy that you found it helpful; if not generic, we all follow some form of mixed conventions that we get from here and there:)
Hi Shinjith ! Thanks for sharing
You're welcome! I'm glad you found the post interesting.
cool article, i wonder if there is one for file naming too
Thanks! It is not a good idea to use the same file naming or folder structure across all technologies, but there are plenty of guides if you're seeking for a specific language or framework; I hope this helps.
I enjoyed this read and do agree that your points are effective disciplines for beginner and veteran developers to practice.
I'm glad you found this post informative and helpful!
you got some typos in there buddy
Loll! Too lazy to fix them, thought everyone would ignore :/. But atleast we can confirm this isn't AI generated
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?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.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.