La bonne façon de commit !

Donc, j'ai récemment publié un article qui explique qu'utiliser un template de message pour git m'a aidé à écrire des commits propres et utiles.

Mais ce template n'a rien de magique et ne fera pas le travail à votre place : c'est un outil utile, mais ça s'arrête là. Je vais vous montrer comment je l'utilise personnellement, et pourquoi ça fonctionne bien - pour moi.

« Pourquoi » : la bonne façon d'écrire vos notes

Avant toute chose, vous voulez être sûr que le message de votre commit sera pertinent. Ce que j'ai appris, c'est que dans presque tous les cas, expliquer pourquoi plutôt que quoi apporte automatiquement 3 choses géniales :

1. Une façon plus simple (pour vos collaborateurs) de comprendre pourquoi vous l'avez fait
2. Une meilleure façon de découper votre développement en différents commits, ce qui vous fait travailler de manière plus flexible
3. Au bout du compte, une qualité plus globale dans vos projets

Voyons voir en quoi ça change tout.

Exemple du quoi :

commit 1
[fix] -> correction d'un bug sur la page de connexion

J'ai corrigé un bug causé par la version de PHP.
J'en ai aussi profité pour nettoyer certains usages dans la classe et refactorer la méthode où le bug apparaissait, parce qu'elle était affreuse !

Dans ce premier exemple, le développeur corrige un bug dans un fichier. Il se rend aussi compte que certains usages étaient inutiles, donc il les supprime pour nettoyer un peu le code. Il commit ensuite le tout en un seul bloc.

Maintenant, si quelqu'un doit travailler sur le projet et consulter tout l'historique git, il ne saura probablement jamais pourquoi le bug est apparu, que le serveur a changé, etc. C'est une vraie perte d'information !

Exemple du pourquoi :

commit 1
[fix] -> correction d'un bug sur la page de connexion

J'ai corrigé un bug causé par la version de PHP parce qu'on a migré notre projet vers un nouveau serveur.

commit 2
[cleanup] -> nettoyage de quelques usages inutiles

J'ai nettoyé certains usages dans la classe parce qu'ils n'étaient plus utilisés depuis un moment indéterminé.

commit 3
[refacto] -> refacto de la méthode de connexion

Le code était affreux donc je l'ai refactoré après avoir corrigé le bug initial dans *commit_1_hash*

Vous voyez qu'il y a pas mal de changements... je vais vous les expliquer pour être sûr que ce soit clair.

En choisissant cette approche, le développeur est obligé de découper les modifications en 3 commits, ce qui rend leur lecture plus simple. Ça apporte aussi pas mal d'avantages en termes de flexibilité (revert d'un commit, cherry-pick etc) et c'est une meilleure façon de procéder en général. De plus, en découpant votre travail en petits morceaux comme ça, vous n'avez même plus forcément besoin de dire quoi vous avez fait puisque ce sera visible au premier coup d'œil ! Cette dernière affirmation n'est vraie que si vous faites du code propre et lisible, d'où les améliorations de qualité dont je parlais plus haut.

On le fait (mon équipe et moi) depuis 2 jours maintenant et on voit déjà tous les changements et avantages que ça nous apporte. Mais ça n'aurait probablement pas été possible sans l'utilisation d'un template de message, comme je le disais au début de cet article.

Comment le faire efficacement

Vous connaissez maintenant la théorie. Mais parfois, ça peut être difficile de l'appliquer à votre workflow sans les bonnes stratégies / outils - on va parler de quelques commandes git spécifiques qui vont vous aider à bien faire les choses.

Par exemple, vous êtes en train de corriger un bug ; malheureusement il y a pas mal de refacto et de nettoyage de code à faire... comment procéder ? Ce sera difficile de : 1) faire le fix, 2) refacto et 3) nettoyer... surtout si votre fonctionnalité est plutôt grosse.

Mon conseil ici est de tout faire en même temps, puis de découper ça en plusieurs commits. Sans les bonnes commandes, ça pourrait être une vraie galère, heureusement git est génial et nous donne ce dont on a besoin !

git add -p (--patch)

Celle-là, vous devriez déjà la connaître. Sinon, apprendre à l'utiliser va vous changer la vie ! Elle va vous demander, morceau par morceau, si vous voulez ajouter un bloc de code à vos fichiers indexés (staged). Comme ça, vous pouvez n'ajouter qu'une partie d'un fichier et pas toutes les modifications que vous avez faites.

git reset -p (--patch)

En gros, l'inverse de git add -p : imaginez que vous ayez indexé (staged) certaines modifications par erreur. Avec cette commande, vous pouvez les parcourir et choisir lesquelles garder en staged ou repasser en unstaged.

git diff --cached

L'option --cached affichera les modifications indexées (staged) et non celles qui ne le sont pas. Utile pour vérifier l'état actuel de votre index.

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

L'option -p vous permettra d'utiliser une interface interactive pour rédiger votre message de commit. Comme ça, vous pouvez faire des messages clairs et explicites, formatés en Markdown. L'option -v affichera toutes les modifications que vous êtes sur le point de commit en bas de votre message. Elle va en gros afficher à la fois un git status et un git diff --cached combinés, pendant que vous éditez votre message.