Let's start with what commit messages are, they basically are messages or tags given along with a commit statement in git so that reviews are easier and the version log is understandable.
To create a successful and understandable revision history teams must agree upon a common commit convention to use in the project, in the present scenario even personal projects would really be easier with such conventions.
Introduction to version control with Git
Version control refers to maintaining the source code and the software with a history log in stages. It is an unavoidable tool in all modern-day industries.
By far, Git is the most widely used version control system in the world. It is a distributed and actively maintained open source project originally developed in 2005 by Linus Torvalds, the famous creator of the Linux operating system kernel.
New to Git? Check out the official getting started guide.
What is a commit message?
The commit command is used to save changes to a local repository after staging in Git. However, before you can save changes in Git, you have to tell Git which changes you want to save for easier backtracking as you might have made tons of edits. A great way to do that is by adding a commit message to identify your changes.
Commit Options
- -m
This option adds a message to commit for easier understanding
git add \*
git commit -m 'new medium blog added'
- a or — all
This option adds all existing tracked including new and edited
git commit -a -m "corrected medium blog"
— amend
This option overwrites the last commit with the present staged changes. This should only be done before you push the staged commits to the server.
git commit --amend -m "overwrite previous blog"
Why should you write good commit messages?
You might wonder why to write a good commit message because it's only you or only your team who understand and know what each other is committing. Just imagine a new team working on your project or expanding your team to a scale where each other do not know what you are committing.
A well-crafted Git commits message is the best way to communicate context about a change to other developers working on that project, and indeed, to your future self.
Have you ever tried running git log on one of your old projects to see the “weird and funny ” commit messages you have used since its inception? It can be hard to understand why you made some changes in the past or what some commits even where, you would wish to have known about the techniques earlier.
How to write commit messages with Git
By now you would have understood the commit message format and its syntaxes.
giving smthing like
git commit -m 'Fix:added y to x'
or
git commit -m 'Fix Typo in readme.md'
Would be understandable on smaller fixes but in case of more detailed fixes this would not work out well
Adding a Detailed Commit message
Command line method
git commit -m 'Fix:xyz bug' -m 'Added Moderator to solve xyz bug in main.py'
The first -m option is the subject (short description/Title), and the next is the extended description (body).
How to write good commit messages
There are several conventions used by different teams and developers to write good commit messages. I’ll only outline some general rules and tips for writing commit messages–you have to decide what convention you want to follow. And if you work for a company or contribute to open source, you have to adapt to their convention.
For consistency, you can use one convention for work and another for personal projects as you might change jobs sometime, and the convention might also change.
Be sure to check out this thread for some amazing commit message conventions or add yours to help someone make a decision.
Here’s a great template of a good commit message originally written by Tim pope
Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, followed by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
If you use an issue tracker, add a reference(s) to them at the bottom,
like so:
Looks great, right? Here’s how you can make yours great too:
- Specify the type of commit:
- feat: The new feature you’re adding to a particular application
- fix: A bug fix
- style: Feature and updates related to styling
- refactor: Refactoring a specific section of the codebase
- test: Everything related to testing
- docs: Everything related to documentation
- chore: Regular code maintenance.[You can also use emojis to represent commit types]
- Separate the subject from the body with a blank line
- Your commit message should not contain any whitespace errors
- Remove unnecessary punctuation marks
- Do not end the subject line with a period
- Capitalize the subject line and each paragraph
- Use the imperative mood in the subject line
- Use the body to explain what changes you have made and why you made them.
- Do not assume the reviewer understands what the original problem was, ensure you add it.
- Do not think your code is self-explanatory
- Follow the commit convention defined by your team
Conclusion
The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.
Want to learn more about Git and become a professional “version controller”? Check out these excellent resources:
- https://try.github.io/
- https://git-scm.com/book/en/v2
- https://www.git-tower.com/learn/
- https://learngitbranching.js.org/
- https://github.com/commitizen/cz-cli
Top comments (0)