The good way to commit !

So, I recently published a post which explains that using a message template for git helped me to write nice and useful commits.

But this template is not magic and won't do the job for you: it's an helpful tool, but that's it. I'm gonna show you how I personally use it, and why it works fine - for me.

"Why": the good way to write your notes

Before anything, you want to be sure that you're commit's message will be pertinent. What I learned is that in almost all case, explaining why instead of what will automatically bring 3 great things:

1. An easier way (for your collaborators) to understand why you did it
2. A better way to split your development into different commits, which make you to work in a more flexible way
3. At the very end, more global quality in your projects

Let's see how it can make the difference.

Example of what:

commit 1
[fix] -> fix a bug on login page

I fixed a bug caused by the PHP version.
Also, I cleaned up some usages in the classe and refactored the method in which the bug appeared since it was awful!

In this first example, the developer fix a bug in a file. He also finds out that some usages where useless so he removes them to clean the code a little bit. He then commits the whole thing.

Now, if someone have to work on the project and check all the git history, he will probably never know the bug appears since the server has changed etc. That's some lost of information!

Example of why:

commit 1
[fix] -> fix a bug on login page

I fixed a bug caused by the PHP version because we migrated our project to a new server.

commit 2
[cleanup] -> clean some useless usages

I cleaned up some usages in the class because they were not used since an undefined period of time.

commit 3
[refacto] -> refacto the login method

The code was awful so I refacto it after fixing the initial bug in *commit_1_hash*

You can see that there are a lot of changes... I'll explain them to be sure it's clear for you.

By choosing this approach, the dev. is forced to split the modifications in 3 commits, making the reading of them easier. It also brings a lot of advantages in term of flexibility (reverting a commit, cherry-pick etc) and is a better way to proceed in general. Furthermore, by splitting your work into little pieces like that, you don't even necessarily need to say what you did since it will be visible at the first sight! This last statement is only true if you make a clean, readable code, thus the quality improvements I was talking before.

We've done it (my team and me) since 2 days rightnow and we already see all the changes and advantages that bring to us. But this may have not happen without the usage of a message template as I said at the beginning of this article.

How to do it efficiently

You now know the theory. But sometimes, it can be hard to apply it to your workflow without the good strategy / tools - we will be talking about some specific git commands that will help you to do it right.

For example, you're working to fix a bug ; unfortunately there is a lot of refactoring and code cleanup to do... how de you proceed? It will be hard to: 1st make the fix, 2sd refacto and 3 clean-up... especially if your feature is somehow big.

My advice here is to do it all at the same time then to split it into multiple commits. Without the good commands it could be a pain in the ass, fortunately git is awesome and provides us what we need!

git add -p (--patch)

This one you should already know. Otherwise, learning to use it will change your life! It will ask you, chunk by chunk, if you want to add a bloc of code to your staged files. That way you can add only parts of a file and not all the modifications you've done.

git reset -p (--patch)

Basically, the opposite of git add -p: imagine that you've had some modifications as staged by error. With this command you can parse them and choose which one you want to keep as staged or change to unstaged.

git diff --cached

The option --cached will display the modifications staged and not the unstaged ones. Usefull to review your current stage state.

git commit -v (--verbose) -p (--patch)

The -p option will allow you to use an interactive interface to write down your commit message. That way you can make clear, explicit messages formatted in Markdown. The -v option will display all the modifications you are going to commit at the bottom of your message. It will basically print both a git status and a git diff --cached combined, while editing your message.