writing proper git commits

technolaaji profile image Mohamad Kalaaji ・5 min read

It was the 28th of August, where my friend send my CV to a small company of 2 senior developers asking to have a junior developer onboard in their team.

after they contact me and arranged a meeting, I was given a task (or it was so call homework). The "homework" was to create an employee directory application where it services basic CRUD (Create, Read, Update, Delete) functionalities.

I was given to use what type of frontend (they use Angular in house but since I have some experience with React so React it was) and Nodejs + Express for backend (they use Nodejs heavily for backend). Part of the "homework" is to go wild with it by including scripts that help and aid in development (example: set a script in your package json to remove your build folder using rimraf [a nodejs package] and build your project to have the latest project possible), use of linters and code formatters, use new technologies like Graphql, and as well using external services like Algolia for searching employees.

They have included a detailed description of how to structure the application in a way they find it efficient, clean, scaleable . And they value code quality and git commit quality

This is not a joke

This is the first time you find someone asking for git commit quality, usually a recruiter will ask for code you have written before so they can review

typically you would provide your github/gitlab/bitbucket link so they can review your code but that doesn't end here: they review something that not all seniors and CTO do focus on and that is git commits

so what happened next? 🤔

I didn't get the job but I've learned something from this "homework", you rarely get this kind of chance anywhere.

Idea of this "homework" is not about flexing your skills (if you can flex your skills then good for you) but rather more into adapting and learning new things as well reviewing yourself

why they focused on git commits anyways? 🙂

turn out that with every version of a website/application/library they developed, they put in the README.md file all of the updates done on each version

having proper git commits help a-lot in populating the README.md file as well if any errors occurred, you can always git revert back to a specific commit

having non proper or poor git commits will cause you to have a hard time remembering which commit is responsible for a specific push (and let's be real, not everyone have a photographic memory to remember everything. We humans can forget and that is okay, really!)

examples of bad git commits

update navbar

here you said that you have updated the navbar, but what did you update in it? 🤔

navbar updated, elements now stacked in a linear way

also still poor because you said that the elements are stack in a linear way but how? why? what was the problem in the first place?

date reverser function for bookings is working

great, you created a function that reverses the date's format but is it inside of the bookings file? why did you create it in the first place? what purpose does it follow?

examples of okay git commits

navbar updated [check description]

- used css-grid instead of flexbox for aligning the elements
- used grid-template-columns with a repeat of 4 columns 1fr wide
- every element is placed in the center to the main grid div tag
- this setting can help us in mobile much faster by switching columns to rows

remember those first two git commits, compare them with this: they are the same but this commit is better to read

I know what is going on and what I used so incase of any errors I can always refer back to this commit

date reverser function on bookings [check description]

- date reverser function was created in the utils folder
- purpose of this function to reverse the format from YYYY-MM-DD to DD-MM-YYYY
- eventhough this should be a backend issue but currently the backend team is busy and we needed a quick fix
- when backend engineers are free, they can reverse it from their side and this function has served its purpose

compare the first date reverser function commit with this one, the purpose you created this function is because the backend team is not free to reverse a date format and you need to have a quick solution to work with

purpose of the [check description]

majority will ignore the description written under those commits and here is why:

the first line written will always will be the title, anything under the title will be considered as body. on Github/Gitlab/Bitbucket the title will show only unless you press on that commit to see the description

adding this to the tittle makes the developer curious of what is written in the body

example of a good git commit

we will use the navbar example

[UPDATE] stacking elements on Navbar [check description]

- [IMPLEMENT] use css-grid instead of flexbox
- [IMPLEMENT] use grid-template-columns repeated 4 times with 1fr wide
- [IMPLEMENT] every element is placed in the center respectively to the parent grid div
- [SUGGESTION] this setting can help us better in mobile development by switching columns to rows
- [FIX] fix padding on each element by decreasing it from 15px to 10px
- [FIX] set the elements div's left margin to auto to be aligned at the end of the parent navbar div automatically
- [UPDATE] remove bootstrap classes and use own made classes

here is a more verbose version of it, it is more detailed. It might look weird yet time consuming but take into consideration the amount of time you will save trying to guess what you did in that commit

I rarely use this until recently because I know what I have done in details whether it was a fix or a new implementation or future suggestions for later

how to write those commits? 🤔 my terminal doesn't allow me

I use VSCode for this purpose (I use VSCode for everything so it makes sense to set it up as my git editor as well)

easiest way to do it is by setting VSCode as your default git editor

first enable VSCode to work in the terminal by setting a path to VSCode (read it here)

then set this in the terminal

git config --global core.editor "code --wait"

this sets VSCode as your core git editor, and whenever you want to commit in git you do it this way:

git commit

and it will open a new window in VSCode, write the commit you want then save it then close the file so it stops waiting for VSCode

you can read about here

Posted on by:


markdown guide

our commits are more like


then gitlab recognise them as links to jira tickets ;)


Actually that is really cool!

But you write that in the title and write a description or how the procedure goes? (Interesting topic since I work with gitlab and jira)


I tag commits with the ticket, and a short overview of what was done.
The ticket has more detail, of someone needs it, there maybe multiple commits for that one ticket as well.

I would also argue that last commit was terrible!
It should have been at least 7 separate commits, which were distinct to each completed change.
You can then revert single problematic commits, rather than loosing ALL those changes if the big commit needs to be rolled back.

yeah I agree on slicing that big commit to small ones.

I've used this technique on freelance projects where I would be doing loads of updates and additions in the least amount of time possible so I tend to forget to commit on each edit.

so I end up pushing them in one big commit and I rarely git reverted back a commit 🤷‍♀️but there was a case scenario where I pushed a huge commit and reverted it ended up rewriting alot of code all over again

and there were times where a big commit saved my life: doing a navbar for a client and she didn't like it and wanted the old navbar back so just reverted one commit rather than typing git log and search for the initial commit for the navbar and git revert back to it

so depends on the case scenario but I agree with you on slicing big commits to small ones

but the ticket trick is worth knowing about!


our commits again are usually the ticket number and a small optional meaningful description i.e.

DEV-1234 mark cross customer call as external
which is automatically gets converted as a jira link on gitlab (we use a jira integration)

(I work in telco btw)

Also same for our branch names. They are ticket numbers DEV-1234 and when a branch is merged on develop /master etc, there is an automated comment on the ticket.

which is handy, because If I see something and I don't understand why it was done like that (poor comments, etc) I can go into the ticket read the description and make sense.


You can use that for your projects but in a professional work environment, it will show a little bit of unprofessionalism.

Even if it looks innocent and cute but business is business

But feel free to do it on your projects


👍 Why so serious Mohamad?

Enjoyed the read btw, keep it up.


What I also like is this: github.com/conventional-changelog/...

Automatic parsing for a neat list on top if needed.