As a developer, you are probably using Git as a version control system for your projects.
When you are done with your modifications, you probably want to add your files to the index and commit them for them to be saved.
Whether you have a Git flow already in place or not, creating Git commits with message is a good practice.
Git commit messages are crucial : they are used in order to describe and share with others what you did.
They are also used when trying to hotfix issues happening on your master branches.
In this tutorial, you are going to learn how you can create Git commits with messages.
You are also going to learn the best practices of Git commit messages and how you should write them.
Git Commit With Message
The easiest way to create a Git commit with a message is to execute “git commit” with the “-m” option followed by your commit message.
$ git commit -m "Describe your commit here"
When using the Git CLI, note that you should restrict your commit message in order for it not to be wrapped.
Usually, a good practice is to keep Git commit messages under 50 characters or less.
If you want to append a description to your Git commit, you will have to use another method.
Git Commit With Description
In some cases, you may want to create a Git commit with a larger description.
Furthermore, you want your Git commit message to fit the character limit on Git.
To create a Git commit message with a large description, you have to execute the “git commit” command without any options. On Linux or in the Git bash, it will open an editor for you to write your Git commit message.
$ git commit
When leaving the editor and creating your Git commit message, you will be able to see that the short message was taken into account to create the commit.
Similarly, if you try to inspect your Git history, you will be able to see that only the short message is visible to other users.
$ git log --oneline --graph
Now that you know the basics of creating Git commit messages, we will see what rules you can use in order to write proper commit messages.
Writing Good Git Commit Messages
Writing good commit messages is crucial to any workflow.
Git commits provide insights on the work performed.
As a consequence, if they are not written properly, you have the risk of not identifying clearly what you have worked on, or what others have worked on.
This can lead to a very messy process where you are not able to perform code integration or to reverse-engineer what you did in the past.
Here is a small list of rules that you can follow to write good Git commit messages :
1 – Keep your Git commit messages short and informative
When you are working on a task, you should be able to clearly identify what you are working on.
There is no such task as “creating a website” or “refactoring the entire codebase”.
# Bad habit $ Created pages for the website # Good habit $ Created the sign-up form front-end and added controls $ Added the Login button to the Login page
Instead, if you divided your big tasks from the beginning, you should have a small set of features that you can work on.
Your Git commit message should reflect the properly divided work you are currently performing.
2 – Git commit messages should reflect your Git flow
When working with Git, choosing a Git flow is essential to ensure that integrations are performed without any regression or additional bugs.
If you are not sure about Git Flow, Atlassian wrote a very useful guide about it : you should read it and choose a Git flow if not done already.
Now that your Git flow is chosen, you can reflect it in your Git commit messages.
For example, if you are working on a feature branch, you can easily write a prefix or a suffix describing the branch you are working on.
$ (on <branch>) Fixed the UI bug when creating a new user $ Fixed the UI bug when creating a new user (on <branch>)
This step is very useful : whenever you are trying to inspect changes done in the past, you will be able to easily identify all the branches associated with a feature.
3 – You are not working alone
Most of the time, you are not working alone on your project : you are working with other developers.
As a consequence, writing good Git commit messages is also a sign that you care about other developers on your team.
When other developers will pull your changes, they will most likely try to understand what you have done.
It is also very likely that your modifications had some kind of impact on other parts of the code that you are not directly aware of.
Being descriptive is the best way to ease the future work that they will have to do.
It might not make a big difference on one or two commits, but the impact is huge when done over several hundred commits.
# Bad habit $ Fixed bug on code # Good habit $ Fixed the NullPointerException when trying to create a user from login
4 – Use good spelling and syntax for your Git commits
This is a very obvious step but you should try to keep good spelling a proper grammar when writing Git commit messages.
Also, syntax should be adapted to the Git commit message : avoid exclamation marks and words that add nothing descriptive or useful to the content of your Git message.
# Bad habit $ Finally fixed the UI page! 😊 # Good habit $ Fixed the UI page by adding an try-catch clause
Usually, Git commit messages should stay neutral and they should only try to convey the intent of the commit.
5 – Use verbs that fit the modifications done
When creating Git commit messages, one of the hardest parts is coming up with verbs that describe the actions performed in the commit.
Did you fix a bug? Did you refactor a class? Did you delete some methods?
# Bad habit $ Wrote some new code for the feature # Good habit $ Added unit-tests to cover the user creation workflow
Choosing the best verbs is actually crucial : there is an actual difference between fixing a bug and hot-fixing a bug for example.
One can be done on one of your feature branches while the other imply that you have performed a modification directly on one of your production branches.
In this tutorial, you learnt how you can write good Git commits with messages.
You saw that it is possible to keep Git commit messages while adding a longer description to your commit.
If you are interested in Git or in Software Engineering in general, we have a complete section dedicated to it on the website, so make sure to check it out!