二分法追蹤迴歸

二分法（Bisect）是一種用來找出軟體迴歸問題的方法。在 GitHub 上的 Godot 原始碼庫 回報錯誤後，貢獻者可能會請你協助進行 二分法追蹤。透過這個流程，貢獻者能更快鎖定導致迴歸的 commit，進而加速修復。你的協助將受到大家的感謝 :)

以下指南說明如何透過二分法找出迴歸。

什麼是二分法追蹤？

Godot 開發者使用 Git 版本控制系統。在 Git 的語境下，二分法（bisect）指的是手動進行 二元搜尋，找出某個迴歸首次出現的時間點。雖然通常用來追蹤錯誤，這個方法也適用於其他非預期的變動，例如效能下降等。

使用官方建構版本加快二分法追蹤

Before using Git's bisect command, we strongly recommend trying to reproduce the bug with an older (or newer) official release. This greatly reduces the range of commits that potentially need to be built from source and tested. You can find binaries of official releases, as well as alphas, betas, and release candidates here.

危險

Godot 各版本的專案檔案可能不相容。請務必在開始追蹤前備份你的專案。

由於向下相容性，建議從最舊版本逐步測試到最新版本，這樣較不會遇到專案無法在編輯器開啟的狀況。同時也建議將專案簡化為最小可重現範例，越精簡的專案越不容易遇到相容性問題。

Git 的 bisect 指令

如果在上述測試流程中，你已找到不會出錯的建構版本，便可開始追蹤迴歸。Git 版本控制系統內建 git bisect 指令，可將流程半自動化：你只要建構引擎、執行並測試即可。

備註

在追蹤迴歸前，你必須先建立從原始碼編譯 Godot 的建構環境。請參考目標平台對應的 編譯 頁面。（從原始碼編譯 Godot 不需要 C++ 程式基礎。）

請注意，若硬體較慢（例如雙核心 CPU），編譯 Godot 可能每次都需要一個小時，全流程甚至耗時數小時。如果你的硬體效能較低，可考慮在這步驟結束，並於 GitHub issue 回報「二分法前」的結果，讓其他貢獻者接續追蹤。

確認 commit 雜湊值

To start bisecting, you must first determine the commit hashes (identifiers) of the "bad" and "good" build. "bad" refers to the build that exhibits the bug, whereas "good" refers to the version that doesn't exhibit the bug.

You can use either a commit hash (like 06acfccf8), the tag of a stable release (like 4.2.1-stable), or a branch like master.

If you're using a pre-release build as the "good" or "bad" build, you can find the commit hash in the Project Manager in the lower-right corner, or in in the Help > About Godot dialog in the Godot editor. The version information will look something like v4.4.beta3.official [06acfccf8], and the commit hash is within the brackets, in this case 06acfccf8. You can click on the version information to copy it, including the commit hash.

Alternately, you can browse the interactive changelog to find commits for all releases, including development builds. The commits will be listed as a range, like commits: a013481b0...06acfccf8, and the second commit is the one you should use for bisecting. You can also browse the Godot Archive, and find the commit hash within the release page linked from the News button.

If you're using a stable release as the "good" or "bad" build, you can use the tag of that release directly, such as 4.2-stable or 4.2.1-stable. A full list of release tags is available on GitHub, and you can also find the actual commit hash that corresponds to a stable release there.

如需指定 master 分支最新狀態，可直接用 master 取代 commit 雜湊。請注意，與標籤釋出或快照 commit 不同，master 會隨時變動。

建構引擎

使用 Git 取得 Godot 原始碼。完成後，在終端機視窗用 cd 切換到 Godot 原始碼資料夾，並輸入下列指令：

# <good commit hash> is hash of the build that works as expected.
# <bad commit hash> is hash of the build exhibiting the bug.
git bisect start
git bisect good <good commit hash>
git bisect bad <bad commit hash>

編譯 Godot，此處假設你已建立好建構環境：

scons

執行引擎

執行 bin/ 資料夾內的二進位檔，並嘗試重現錯誤。

備註

請再次確認的輸出檔名 在 bin/ 內，確保你執行的是剛剛編譯出來的二進位檔。不同版本的 Godot 會產生不同名稱的二進位檔。

若此建構版本**仍然**有錯誤，請執行以下指令：

git bisect bad

如果此建構版本**沒有**此錯誤，請執行以下指令：

git bisect good

輸入上述任一指令後，Git 會切換到另一個 commit。你需再次建構 Godot、測試是否重現錯誤，並依據結果輸入 git bisect good 或 git bisect bad。這個流程需重複數次，commit 範圍越大，步驟越多。通常 5 到 10 步就能找出大多數迴歸；Git 會提示剩餘步數（最壞情況下）。

當步驟完成後，Git 會顯示該迴歸首次出現的 commit 雜湊值。請把這個雜湊值留言到對應的 GitHub issue，協助問題修復。再次感謝你的貢獻 :)

也參考

你可以在 這裡 參閱完整的 git bisect 說明文件。