We all have been working with Git(One of the most popular Versions Control Systems) for quite a long time now. We all are aware of how useful it is in our day to day life as developers.
Git commits are one of the crucial and underrated parts of a Git repository. As a project grows over time, commit messages gives information about where and what is changed. So these messages must reflect the changes in a short and precise manner.
In this blog, I'll discuss the importance of a good commit message and the standards we follow at Zysk. You can implement this guide as it is or pick and choose parts from it.
Let's get started!!
Why is a Git commit message important
Let's take an example of a commit log from one of our repositories.
These commits are from one of our old projects. If you are wondering who Chandan is, he is our client😁. I'm assuming the changes were suggested by Chandan; that's why the commit message says chandan changes. Easy right💁♀️
Now compare it with the commit log from one well-maintained Git repository
Which one is easier to read?
By reading the first Git log, we can barely understand the changes made to the codebase, but the second one is concise and clear in terms of the changes being made.
Writing a good commit message is crucial to any workflow as it provides insights about the changes. If the messages are not written correctly, we will not be able to identify what we have worked on and what others have worked on.
A well-organized commit message leads to
- Structured commit history, which defines what changes have been made in every release
- Defines the nature of change in your codebase, which can give helpful insights to teammates and other stakeholders
- Peer Code reviews can be done independently. Your commit messages serve as a guide for the reviewers to review code.
Writing a good commit message
Format for a good commit message
Type(scope): subject <body> <footer>
Type of the commit:
A commit message contains the following elements to communicate the change.
1. feat: A new feature being added to the application 2. fix: A bug fix 3. style: Features and updates related to styling 4. refactor: Refactoring a specific section in the codebase 5. test: everything related to testing 6. docs: If you are adding/updating documentation in your codebase 7. chore: Regular code maintenance
Scope of the commit(Optional):
Scope of the commit must be a Noun that describes the module affected by this change, or simply Epic name from Jira, enclosed within parentheses.
feat (user management) fix (login)
The subject contains a short description of the changes being made. It should not be more than 50 characters(GitHub's UI will automatically truncate subject lines having more than 72 characters), should not end with a period, and should be written in an imperative mood. For example, instead of saying Added validation to the login form or Adds validation to login the form, you should say Add validation to the login form.
feat (user management): integrate login API fix (login): add validation for email
Use Body to explain the changes you have made in the commit. You can use Body when you are pushing a complex commit. Not all commits require a body. A blank line must be added between the Subject and Body, and it should not exceed 72 characters.
feat (login): create login form - create a form with email and password fields - added validation - integrated API
Like Body, Footer is also optional. Use Footer to reference the issues(ticket number from Jira) affected by the commit. A blank line must be added between the Body and the Footer.
feat (login): create login form - create a form with email and password fields - added validation - integrated API Resolves: AGA-795, AGA-796
A quick recap
- Separate subject from Body with a blank line
- Limit Subject line to 50 characters
- Do not end a subject line with a period
- Use the imperative mood in the Subject line
- Limit body to 72 characters
- Use the Body to explain what and Why vs How
Let me know your thoughts. Happy coding 🙌