How to make Caipirinha using git log

Writing good commit messages

Brazil’s national cocktail

Writing good commit messages is essential and is the best way to justify changes in your code. I know you want to do it but where to start?

Be atomic

The first thing to do when deciding to commit a set of changes is to make it atomic i.e. make it small enough in a way that it still has logical meaning

Don’t create all the steps of your recipe in one commit, atomic doesn’t mean all in one:

d427050817 Get a glass add some ice cubes and add sugar, place freshly squeezed lime juice, pour 2 shots of cachaça and stir well until combined

Do break it into logical steps and join only what makes sense together:

d427050817 Get a glass
6a442c4d52 Add some ice cubes
...

A good message

The message is extremely important, so a message that gives the reasons and motivation for change is more useful than the ones that try to describe the change itself. Remember that Git saves the difference of your changes and give you the task of describing why it happens that way.

If all your commit messages look good, things will be a lot easier for you and the developers you work with

Don’t be short and presume the obvious. It may not be enough to cut the limes in half:

d427050817 Get a glass
6a442c4d52 Added some ice cubes and lime
ff174e64ab Adding cachaça and stir

Do be talkative and as explicit as needed as this can change the taste of your Caipirinha:

d427050817 Get a glass
6a442c4d52 Add some ice cubes
b231494c6d Place freshly squeezed lime juice
ff174e64ab Pour 2 shots of cachaça

Review

Having a story in your git log will make a huge difference in how you and others perceive your project.

Don’t write a confusing recipe because you wrote the wrong quantity of sugar by mistake:

d427050817 Get a glass
6a442c4d52 Add some ice cubes
b7b9fa56aa Add sugar
b231494c6d Place freshly squeezed lime juice
8bd07b9259 Stir well until combined
ff174e64ab Pour 2 shots of cachaça
449af37029 Reduce quantity of sugar

Do rewrite into well-organised steps:

fod427050817 Get a glass
6a442c4d52 Add some ice cubes
b7b9fa56aa Add sugar
449af37029 Reduce quantity of sugar
b231494c6d Place freshly squeezed lime juice
ff174e64ab Pour 2 shots of cachaça
8bd07b9259 Stir well until combined

And if necessary squash them together, it may be hard to remove sugar from your recipe after it has been added:

d427050817 Get a glass
6a442c4d52 Add some ice cubes
b7b9fa56aa Add sugar
b231494c6d Place freshly squeezed lime juice
ff174e64ab Pour 2 shots of cachaça
8bd07b9259 Stir well until combined

Make it useful

Commit messages are all searchable and are always up to date with your code changes. Start using git log now:

git log --oneline --grep sugar
b7b9fa56aa Add sugar

Isn’t that beautiful? Other useful examples:

git log --grep="lime"
git log --author=Milhomem
git blame
git help log

Good or bad?

Now look at these real case scenarios and judge by yourself if they're good or bad.

commit 90eafbd
Retry on authentication errors
 
MMCourier API is very unstable. It returns authentication error randomly even when the username and password are ok. We are in contact with them to fix this on their side but in the meantime, this will minimise the impact on packing we are having
diff --git a/MMCourier/Request.php b/MMCourier/Request.php
index 8ce765fa11..5272b25bad 100644
--- 
@@ -2,12 +2,14 @@
$client = $this->getClient($order, $originWarehouse, $carrierOption);
                 try {
-                    $response = $client->book($apiOrder);
-                    if ($response->getErrors()) {
-                        throw new Exception('MMCourier booking response contains error');
-                    }
+                    $response = $this->book($client, $apiOrder);
+                } catch (AuthenticationException $exception) {
+                    $response = $this->book($client, $apiOrder);
                 } catch (Exception $e) {

The above looks good as it explains the motivation for calling the same method twice when it’s not logical to do.

commit 22d6b10
Fetch the MMCourier zone code properly when printing the label
diff --git a/MMCourier.php b/MMCourier.php
index 05e44bdf2d..13244a4d92 100755
@@ -54,7 +54,7 @@
$pricesTable = $this->getShipmentMMCourierPricesTable();
-        $result = $pricesTable->fetchRow(['postcode' => $postcode]);
+        $result = $pricesTable->findOneByCriteria([PricesRow::POSTCODE => $postcode]);
         return (int)$result[PricesRow::MMCOURIER_ZONE_CODE] ?? 0;
     }
 }

The above looks very bad as it does not explain why findOneByCriteria() is better than fetchRow() in that case 🤷‍‍

Finally everyone’s favourite commit message: WIP 🤦‍

git log --oneline --grep WIP
37f03b6500 [feature/WEB-983] - WIP; fixes
88cbdced75 [feature/WEB-983] - WIP
0257da25f2 [feature/WEB-983] - WIP starting to bring everything together
fa6e7fde76 [feature/WEB-983] - WIP
c6ef670061 [feature/WEB-983] - WIP, bringing it all together
463d4ce7af [feature/WEB-1029] - WIP
3aa2eeebeb [feature/WEB-983] - refactor product page js; WIP
5f25bfc921 [feature/WEB-983] - WIP; adapterised oauth service
b91658a872 [feature/WEB-983] - WIP
854329618f [feature/WEB-983] - WIP
dfb2b1601e [feature/WEB-983] - WIP

I’m sure you’ll never share this kind of commit message anymore 👊

If you enjoyed this article, please give us a CLAP (or 50!) below and be sure to subscribe to THE ICONIC Tech publication!