Web・開発

Git Bisect: バグを導入したコミットを見つける

Git Bisect: Find the Commit That Introduced a Bug

ある機能は昨日は動作していたが、今日では失敗します。Git bisectを使ってリグレッションを導入したコミットを特定し、テストを自動で実行し、結果を安全に調査する方法を学びましょう。

先週動作していたウェブサイトが、今日はチェックアウト計算の誤り、JavaScriptコンポーネントの反応不良、またはPHPエンドポイントの予期せぬデータ返却によって動作しなくなっています。

バグがGitの履歴のどこかに発生したことはわかっていますが、最後の動作バージョン以降、リポジトリには数十または数百のコミットが含まれています。すべてのコミットを開き、すべてのdiffを読むことは、めったに最速の解決策ではありません。

Gitには、まさにこの状況に対応するために設計されたツールが用意されています:git bisect。すべてのコミットを調べる代わりに、バイナリサーチを使用して問題を最初に導入したリビジョンを特定します。信頼できるテストがあれば、調査を自動化できます。

このチュートリアルでは、小さなPHPプロジェクトを作成し、意図的にリグレッションを導入し、Git bisectを使用して特定し、同じテクニックを実際のプロジェクトに適用する方法を学びます。

1. Git bisectの仕組み

アプリケーションがコミットAでは動作し、コミットHでは失敗すると仮定します。Git bisectには2つの基準点が必要です:正常なコミット(機能が確実に動作している)と不良なコミット(バグが確実に存在している)です。

Gitは中間リビジョンをチェックアウトします。テストを行い、動作するかどうかを報告し、Gitは残りの検索範囲を縮小します。動作を一貫して分類できると仮定すると、約128個の候補コミットに対して、バイナリサーチは通常、すべての128個を調べる代わりに約7回のテストを必要とします。

公式Gitドキュメントは、プロセスの説明と制限を記載しています。

2. 再現可能なPHPリグレッションを作成する

小さな価格計算関数を作成します。フレームワーク、データベース、Composerパッケージ、またはウェブサーバーは必要ありません。GitとPHP CLIがインストールされている必要があり、Gitはコミット用に著者名とメールアドレスを構成する必要があります。

ディレクトリを作成し、リポジトリを初期化します:

mkdir git-bisect-demo
cd git-bisect-demo
git init

price.phpを作成します:

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price - $discount;
}

期待される動作はシンプルです:finalPrice(100, 20)は80を返します。

動作するバージョンをコミットします:

git add price.php
git commit -m "Add working price calculation"

次に、関連性のない変更を作成します:

echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"

最後に、price.phpの計算を変更してバグを導入します:

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price + $discount;
}

壊れたバージョンをコミットします:

git add price.php
git commit -m "Refactor price calculation"

これで、プロジェクトには3つのコミットがあり、最後のコミットに意図的なリグレッションが含まれています。

3. リグレッションを手動で特定する

まず、作業ツリーがクリーンであることを確認します:

git status --short

このコマンドは出力を生成するべきではありません。未コミットの作業がある場合は、開始前に適切にコミットするか、スタッシュします。

ここでGit bisectを起動します:

git bisect start
git bisect bad HEAD
git bisect good HEAD~2
Illustration of the article's main concept

ここでは、HEADは壊れたリビジョンであり、HEAD~2は最初の動作するコミットを指しています。Gitは中間コミットをチェックアウトします。

計算をテストします:

php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'

出力が80の場合、そのリビジョンを良好とマークします:

git bisect good

出力が120の場合、不良とマークします:

git bisect bad

Gitは最初の不良リビジョンを特定するまでコミットの選択を続けます。この3コミットのデモでは、1つの中間リビジョンのテストのみが必要です。

終了したら、元のブランチを復元します:

git bisect reset

bisect中、Gitは通常、歴史的なリビジョンをデタッチドHEAD状態でチェックアウトします。git bisect resetは、調査前のリビジョンに戻ります。

4. git bisect runで調査を自動化する

バグが視覚検査を必要とする場合、手動でのテストは役立ちます。しかし、動作をコマンドで確認できる場合、自動化の方が効率的です。

Gitはgit bisect run <command>をサポートしています。コマンドは終了コードで結果の通信を行います:

終了コード 意味
0 良好なリビジョン
1–124 または 126–127 不良なリビジョン
125 このリビジョンをテストできません
その他の値 調査を中止

これらのルールは、公式Git bisectマニュアルに基づいています。

テストスクリプトをリポジトリの外に作成します。例えば、../check-price.phpのようにします:

<?php

declare(strict_types=1);

require __DIR__ . '/git-bisect-demo/price.php';

exit(finalPrice(100, 20) === 80 ? 0 : 1);

スクリプトは、プロジェクトフォルダがgit-bisect-demoと名前が付けられ、check-price.phpの隣にあると仮定します。これらのコマンドは、プロジェクトフォルダ内から実行します:

git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset

Gitは、最初の不良コミットが特定されるまで、選択された歴史的なリビジョンでテストを実行します。テストスクリプトがリポジトリの外にあるため、古いリビジョンをチェックアウトしてもリポジトリが削除されることはありません。

実際のプロジェクトでは、安定したテストコマンド、または調査対象の歴史的なリビジョンで動作する外部テストスクリプトを使用します。

5. このテクニックを実際のウェブプロジェクトに適用する

同じワークフローは、WordPressプラグイン、Joomla拡張機能、JavaScriptアプリケーション、またはPHPライブラリにも適用できます。

チェックアウト機能が最新バージョンで壊れているが、リリースv1.4.0では動作していたと仮定します。まず、リリースが実際に良好であることを確認し、次に開始します:

git bisect start HEAD v1.4.0

プロジェクトに、選択したリビジョン間で動作するPHPUnitテストがある場合、手動で実行できます:

vendor/bin/phpunit tests/CheckoutTest.php

各テスト後、git bisect goodまたはgit bisect badを報告します。

テストが確実に自動化されている場合:

git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset

歴史的なコミットでは、異なるPHPバージョン、依存関係、データベーススキーマ、またはビルドツールが必要になる場合があります。環境が互換性がないためにテストが失敗しても、必ずしもリグレッションを示しているわけではありません。テスト環境が関連する歴史的なバージョンを再現できることを確認してください。

Technical workflow illustration

6. 古いコミットがテストできない場合はどうすればよいですか?

時々、歴史的なリビジョンが関連性のない理由でビルドに失敗することがあります。自動的に不良とマークしないでください。

次のコマンドを使用します:

git bisect skip

Gitは別の候補を試します。自動テストでは、終了コード125がGitにリビジョンをスキップするように指示します。

スキップするコミットが多すぎると精度が低下します。リグレッションの隣にテストできないコミットがある場合、Gitは複数の可能な犯人を報告し、1つの正確なコミットではなくなります。

長期的な良い慣行は、再現可能な開発環境を維持し、依存関係のバージョンを固定し、重要なリグレッション・テストを関連性のないインフラから独立させることです。

7. バグを導入したコミットを調査する

Gitが最初の不良コミットを特定したら、それを調査します:

git show <commit-hash>

変更されたファイルを確認するには:

git show --stat <commit-hash>

特定のファイルを調査するには:

git show <commit-hash> -- price.php

最初の不良コミットは、バグの唯一の原因である必要はありません。 コミットは、以前に隠れていた問題を明らかにしたり、別の変更と相互作用したり、以降変更された外部サービスに依存したりすることがあります。

特定されたコミットを使用して根本原因を調査しますが、そのコミットのすべての行が自動的に不正であることを示すものではありません。

8. 一般的な問題と解決策

バグが一貫して発生しない

テストが同じリビジョンで時々合格し、時々失敗する場合、bisectの結果は信頼できなくなります。テストを複数回実行し、可能な限りタイミングの依存関係を排除し、外部入力を制御します。繰り返しテストは信頼性を向上させますが、調査時間を増やします。

テストがすべての歴史的なリビジョンで失敗する

既知の良好なコミットが本当に良好であることを確認します。新しいbisectセッションを開始する前に、そのリビジョンを別途チェックアウトし、テストを実行します。そこでも失敗する場合は、テストまたは環境が不正かもしれません。

Gitがリビジョンの切り替えを拒否する

未コミットの変更があると、チェックアウトが妨げられることがあります。git statusを確認し、変更を保持してから再起動します。git reset --hardなどの破壊的なコマンドは、完全に理解している場合にのみ使用し、捨てられる内容を把握しておいてください。

履歴に多くのマージコミットが含まれている

複雑なリポジトリの場合、Gitは```bash git bisect start --first-parent HEAD v1.4.0



これは、first-parent履歴に従い、マージを通じて導入されたリグレッションの調査に役立ちます。これにより、考慮されるコミットが変更されるため、これは通常のbisectの普遍的な置き換えではありません。

### バグが本番データに依存している

歴史的なアプリケーションコードをライブ本番データベースに対して実行しないでください。サニタイズされたフィクスチャと再現可能なスキーマを備えた分離されたテスト環境を使用します。古いリビジョンには、本番と互換性のないマイグレーションや仮定が含まれている場合があります。

## 9. 実践的なデバッグチェックリスト

- バグが再現可能であることを確認します。
- 1つの動作することが知られているリビジョンと、1つ失敗することが知られているリビジョンを特定します。
- 未コミットの作業を保護します。
- 明確な合格/不合格結果を持つ信頼できるテストを定義します。
- 外部サービスとテストデータを一貫させます。
- 真にテストできないリビジョンには`git bisect skip`を使用します。
- 特定されたコミットを調査し、根本原因を検証します。
- 終了するには`git bisect reset`を使用します。

## 結論

Git bisectは、不確実なデバッグタスクを構造化された調査に変えます。最近のどの変更がアプリケーションを壊したかを推測するのではなく、動作するリビジョンと壊れたリビジョンを特定し、Gitが歴史を絞り込むようにします。

このテクニックは、自動テストと組み合わせることで特に強力になります。数百のコミットに隠れたリグレッションは、しばしば数回のチェックで特定できます。

長期にわたるPHPプロジェクト、WordPressプラグイン、Joomla拡張機能、またはJavaScriptアプリケーションを維持する開発者にとって、`git bisect`は、日常的な分岐やマージを超えた最も有用なGitコマンドの1つです。