Kassis Netz / blog

It’s about the most stupid commit message ever.

Recently I stumbled upon this again and this time I decided to write about it because it really freaks me sometimes.

How would your next commit message read? “Second commit”? And the next? Sure, this might be good if you want to learn numbers in a foreign language, but nothing more. I wonder if there will ever be a “final commit” commit message.

I read so many examples where the above mentioned commit message is shown. I can only hope that this is only because it’s used in an example but even then – and actually it might be even worse. An example is meant to teach, especially (for the given topic) less experienced people and it’s very often used by very beginners. So why not teaching them the correct things? Reading about “Initial commit” commit messages tells them that it’s right and they start using it. What a mess!

So what’s a commit message? It tells the reader what this commit is about, what he gets when he this commit is applied to the project, and this in terms of functionality to the app it belongs to. Sure the developer will get an initial commit but what’s the functionality or content to the app? It stays unclear. You might get the app skeleton but also only a README with some notes.

There’s a fairly good approach to meaningful commit messages that’s btw also used by git itself: Tell the developer what this commit does when applied to the code base – summarized! Use a form that can be read:

If applied to the code base, this commit will Merge branch feature into master

According to this schema, name your commit “Do something…” or speaking about your initial commit, name it “Create new rails app” or “Add README with project description” or maybe even better only “Add project description” - whatever fits best. Now you know what the first commit is about.

I don’t want to go into too much detail about commit messages themselves – I would only repeat what others have stated before. A very good and detailed article with references can be found here.

I by myself go one step further, especially for tasks I’m learning or I’m not performing frequently, and add commands I used to create this commit if there is one. E. g.

Create new rails app

Command: rails new myapp -T -d mysql"

Remember: The very first line of each commit should be the action as described above and it’s considered to be a title rather than sentence. Therefore there’s no full stop at the end. If you want to express more in the message, the next line must be empty, followed by the sentences that describes in more detail or adds notes like

Closes: #731

which might even automatically close the corresponding issue when pushed. This is also the structure I use for my additions.