À titre d’exemple, supposons que vous essayez de trouver le commit qui a cassé une fonctionnalité qui était connue pour fonctionner dans la version v2.6.13-rc2 de votre projet. Vous démarrez une session de bissection comme suit :

Une fois que vous avez spécifié au moins un mauvais et un bon commit, git bisect sélectionne un commit au milieu de cette plage d’historique, l’extrait et affiche quelque chose de similaire à ce qui suit :

Vous devez maintenant compiler la version extraite et la tester. Si cette version fonctionne correctement, tapez

Si cette version est cassée, tapez

Ensuite, git bisect répondra par quelque chose comme

Continuez à répéter le processus : compiler l’arbre, le tester, et selon qu’il est bon ou mauvais lancer git bisect good ou git bisect bad pour demander le prochain commit qui a besoin d’être testé.

Finalement, il ne restera plus de révisions à inspecter et la commande affichera une description du premier mauvais commit. La référence refs/bisect/bad sera laissée pointant vers ce commit.

Après une session de bissection, pour nettoyer l’état de bissection et revenir à la HEAD d’origine, exécutez la commande suivante :

Par défaut, cela retournera votre arbre à la validation qui a été vérifiée avant le git bisect start. (Un nouveau git bisect start fera également cela, car il nettoie l’ancien état de bissection.)

Avec un argument optionnel, vous pouvez revenir à un commit différent à la place :

Par exemple, git bisect reset bisect/bad extraira la première mauvaise révision, tandis que git bisect reset HEAD vous laissera sur le commit de bissection actuel et évitera du tout de changer de commits.

Parfois, vous n’êtes pas à la recherche du commit qui a introduit une rupture, mais plutôt pour un commit qui a causé un changement entre un autre « vieil » état et « nouvel » état. Par exemple, vous pouvez être à la recherche du commit qui a introduit un correctif particulier. Ou vous pouvez être à la recherche du premier commit dans lequel les noms de fichiers de code source ont finalement tous été convertis à la norme de nommage de votre entreprise. Ou quoi que ce soit.

Dans de tels cas, il peut être très déroutant d’utiliser les termes "good" (« bon ») et "bad" (« mauvais ») pour désigner « l’état avant le changement » et « l’état après le changement ». Ainsi, au lieu de cela, vous pouvez utiliser les termes "old" (« ancien ») et "new" (« nouveau »), respectivement, à la place de "good" et "bad". (Mais notez que vous ne pouvez pas mélanger "good" et "bad" avec "old" et "new" dans une seule session.)

Dans cette utilisation plus générale, vous fournissez à git bisect un « nouveau » commit qui a une certaine propriété et un « vieux » commit qui n’a pas cette propriété. Chaque fois que git bisect vérifie un commit, vous testez si ce commit a la propriété. Si c’est le cas, marquer le commit comme « nouveau » ; sinon, marquez-le comme « vieux ». Lorsque la bissection est terminée, git bisect signalera quel commit introduit la propriété.

Pour utiliser "ancien" et "nouveau" au lieu de "bon" et "mauvais", vous devez exécuter git bisect start sans commit en tant qu’argument et ensuite exécuter la commande suivante pour ajouter les commits :

pour indiquer que le commit était avant le changement envisagé, ou

pour indiquer qu’il était avant.

Pour obtenir un récapitulatif des termes utilisés actuellement, utiliser

Vous pouvez obtenir juste l’ancien terme avec git bisect terms --term-old ou git bisect terms --term-good ; git bisect terms --term-new et git bisect terms --term-bad peuvent être utilisés pour apprendre comment appeler les commits plus récents que la modification recherchée.

Si vous souhaitez utiliser vos propres termes au lieu de "bad"/"good" ou "new"/"old", vous pouvez choisir les noms que vous voulez (sauf les sous-commandes de bisect existantes comme reset, start, …​) en commençant la bissection par

Par exemple, si vous recherchez un commit qui a introduit une régression de performance, vous pouvez utiliser

Ou si vous cherchez le commit qui a corrigé un bogue, vous pouvez utiliser

Ensuite, utiliser git bisect <ancien-terme> et git bisect <nouveau-terme> à la place de git bisect bon et git bisect mauvais pour marquer les commits.

Pour voir les suspects restants dans gitk, lancez la commande suivante pendant le processus de bisection (la sous-commande view peut être utilisée comme alternative à visualize) :

Git détecte un environnement graphique à travers diverses variables d’environnement : DISPLAY, qui est défini dans les environnements X Window System sur les systèmes Unix. SESSIONNAME, qui est défini sous Cygwin dans des sessions de bureau interactives. MSYSTEM, qui est défini sous Msys2 et Git pour Windows. SECURITYSESSIONID, qui peut être défini sur le macOS lors de sessions de bureau interactives.

Si aucune de ces variables d’environnement n’est pas définie, git log est utilisé à la place. Vous pouvez également donner des options de ligne de commande telles que -p et`--stat`.

Après avoir marqué les révisions comme bonnes ou mauvaises, donnez l’ordre suivant pour montrer ce qui a été fait jusqu’à présent :

Si vous découvrez que vous avez fait une erreur en spécifiant l’état d’une révision, vous pouvez enregistrer la sortie de cette commande dans un fichier, la modifier pour supprimer les entrées incorrectes, puis émettre les commandes suivantes pour revenir à un état corrigé :

Si, au milieu d’une session bisect, vous savez que la révision suggérée n’est pas bonne à tester (par exemple, elle ne parvient pas à se construire et vous savez que l’échec n’a rien à voir avec le bogue que vous poursuivez), vous pouvez sélectionner manuellement une validation proche et tester celle-ci à la place.

Par exemple :

Ensuite, compilez et testez la révision choisie, puis marquez la révision comme bonne ou mauvaise de la manière habituelle.

Au lieu de choisir vous-même un commit proche, vous pouvez demander à Git de le faire pour vous en émettant la commande :

Cependant, si vous sautez un commit adjacent à celui que vous recherchez, Git ne pourra pas dire exactement lequel de ces commits était le premier mauvais.

Vous pouvez également sauter une série de commits, au lieu d’un seul, en utilisant la notation de plage. Par exemple :

Cela indique au processus bisect qu’aucun commit après v2.5, jusqu’à v2.6 inclus, ne doit être testé.

Notez que si vous souhaitez également sauter le premier commit de la plage, vous devrez émettre la commande :

Cela indique au processus de bissection que les commits entre v2.5 et v2.6 (inclus) doivent être ignorés.

Vous pouvez réduire davantage le nombre d’essais, si vous savez quelle partie de l’arbre est impliquée dans le problème que vous recherchez, en spécifiant les paramètres de spécificateur de chemin lors de la commande bisect start :

Si vous connaissez à l’avance plus d’un bon commit, vous pouvez réduire l’espace de bissection en spécifiant tous les bons commit immédiatement après le mauvais commit lorsque vous lancez la commande bisect start :

Si vous avez un script qui peut dire si le code source actuel est bon ou mauvais, vous pouvez bissecter en émettant la commande :

Notez que le script (my_script dans l’exemple ci-dessus) doit se terminer par le code 0 si le code source actuel est bon/ancien, et se terminer par un code entre 1 et 127 (inclus), sauf 125, si le code source actuel est mauvais/nouveau.

Tout autre code de sortie fera avorter le processus de bissection. Il convient de noter qu’un programme qui se termine par exit(-1) laisse $ ? = 255, (voir la page de manuel exit(3)), car la valeur est masquée avec & 0377.

Le code de sortie spécial 125 doit être utilisé lorsque le code source actuel ne peut pas être testé. Si le script se termine avec ce code, la révision en cours sera ignorée (voir git bisect skip ci-dessus). 125 a été choisi comme la valeur la plus sensée à utiliser dans ce but, parce que 126 et 127 sont utilisés par les shells POSIX pour signaler un statut d’erreur spécifique (127 indique une commande non trouvée, 126 indique une commande trouvée mais non exécutable - ces détails n’ont pas d’importance, car ce sont des erreurs normales dans le script, en ce qui concerne le bisect run).

Vous pouvez souvent constater que pendant une session bisect, vous souhaitez que des modifications temporaires (par exemple s/#define DEBUG 0/#define DEBUG 1/ dans un fichier d’en-tête, ou "la révision qui n’a pas ce commit a besoin que ce patch soit appliqué pour contourner un autre problème qui n’intéresse pas cette bisection") soient appliquées à la révision testée.

Pour faire face à une telle situation, une fois que le git bisect interne a trouvé la prochaine révision à tester, le script peut appliquer le patch avant la compilation, exécuter le vrai test, puis décider si la révision (éventuellement avec la rustine nécessaire) a passé le test et ensuite rembobiner l’arbre à l’état vierge. Enfin, le script doit se terminer avec l’état du test réel pour laisser la boucle de commande git bisect run déterminer le résultat final de la session bisect.

Utilisez git bisect pour obtenir une courte description d’utilisation, et git bisect help ou git bisect -h pour obtenir une longue description d’utilisation.