英語

二分查找回歸

本文件描述瞭如何使用 git bisect 來查詢導致某些功能失效的原始碼更改 -- 例如，在從 Linux 6.0 升級到 6.1 後，某些功能停止工作。

本文重點介紹該過程的要點。如果您是核心二分查詢的新手，最好遵循 如何驗證錯誤和二分查找回歸：它從頭到尾地描述了所有內容，同時涵蓋了多個方面，甚至核心開發人員有時也會忘記。 這包括儘早檢測到二分查詢會浪費時間的情況，因為沒有人會在意結果 -- 例如，因為問題發生在核心將其自身標記為“tainted”之後，發生在已放棄的版本中，已被修復，或者是由您或您的 Linux 發行版執行的 .config 更改引起的。

使用二分查詢查詢導致核心問題的更改

注意：以下過程假定您已為二分查詢做好一切準備。 這包括擁有包含適當原始碼的 Git 克隆，安裝構建和安裝核心所需的軟體，以及儲存在安全位置的 .config 檔案（以下示例假定為“~/prepared_kernel_.config”）以用作每個二分查詢步驟中的原始基本配置；理想情況下，您還想出了一種完全可靠且直接的方法來重現迴歸。

  • 準備工作：啟動二分查詢，並告訴 Git 您認為可以正常工作和已損壞的歷史記錄點，Git 將其稱為“good”和“bad”

    git bisect start
git bisect good v6.0
git bisect bad v6.1

    除了像“v6.0”和“v6.1”這樣的 Git 標籤之外，您還可以指定提交 ID。

  1. 將您準備好的 .config 複製到構建目錄中，並根據 Git 檢出的用於測試的程式碼庫的需求對其進行調整

    cp ~/prepared_kernel_.config .config
make olddefconfig

  2. 現在構建、安裝和啟動核心。 這可能會由於不相關的原因而失敗，例如，當在二分查詢的當前階段發生編譯錯誤時，以後的更改會解決該錯誤。 在這種情況下，執行 git bisect skip 並返回到步驟 1。

  3. 檢查剛剛構建的核心中迴歸的功能是否正常。

    如果它工作正常，請執行

    git bisect good

    如果它已損壞，請執行

    git bisect bad

    請注意，即使一次出錯也會使剩餘的二分查詢完全偏離方向。 為了防止以後不得不重新開始，因此您需要確保告訴 Git 的內容是正確的； 因此，如果您的重現器不可靠，通常最好多花幾分鐘進行測試。

    發出這兩個命令中的一個後，Git 通常會檢出另一個二分查詢點，並列印類似“Bisecting: 675 revisions left to test after this (roughly 10 steps)”的內容。 在這種情況下，返回到步驟 1。

    如果 Git 而是列印類似“cafecaca0c0dacafecaca0c0dacafecaca0c0da is the first bad commit”，則您已完成二分查詢。 在這種情況下，請移至下面的下一點。 請注意，在顯示該行後，Git 會立即顯示有關罪魁禍首的一些詳細資訊，包括其補丁描述； 這很容易填滿您的終端，因此您可能需要向上滾動才能看到提及罪魁禍首的提交 ID 的訊息。

    如果您錯過了 Git 的輸出，您可以隨時執行 git bisect log 來列印狀態：它將顯示剩餘的步驟數或提及二分查詢的結果。

  • 建議的補充任務：將二分查詢日誌和當前的 .config 檔案放在一邊，以用於錯誤報告； 此外，告訴 Git 將原始碼重置為二分查詢之前的狀態

    git bisect log > ~/bisection-log
cp .config ~/bisection-config-culprit
git bisect reset

  • 推薦的可選任務：嘗試在最新的程式碼庫之上還原罪魁禍首，並檢查這是否修復了您的錯誤； 如果是這種情況，它將驗證二分查詢，並使開發人員能夠透過還原來解決迴歸。

    要嘗試此操作，請更新您的克隆並檢出最新的主線。 然後告訴 Git 透過指定其提交 ID 來還原更改

    git revert --no-edit cafec0cacaca0

    Git 可能會拒絕此操作，例如，當二分查詢落在合併提交上時。 在這種情況下，放棄嘗試。 如果 Git 無法自行還原罪魁禍首，因為以後的更改依賴於它，也執行相同的操作 -- 至少除非您二分查找了穩定或長期核心系列，在這種情況下，您需要檢出其最新的程式碼庫並在那裡嘗試還原。

    如果還原成功，請構建並測試另一個核心，以檢查還原是否解決了您的迴歸。

這樣，該過程就完成了。 現在按照 報告問題 中的描述報告迴歸。

二分查詢 linux-next

如果您遇到僅發生在 linux-next 中的問題，請在 linux-next 分支“stable”和“master”之間進行二分查詢。 以下命令將為您新增為名為“next”的遠端的 linux-next 樹啟動該過程

git bisect start
git bisect good next/stable
git bisect bad next/master

“stable”分支指的是當前 linux-next 版本（在“master”分支中找到）所基於的 linux-mainline 的狀態 -- 因此前者應該沒有出現在 -next 中但未出現在 Linus 的樹中的任何問題。

這將跨越廣泛的更改進行二分查詢，您可能在以前的 linux-next 版本中使用過其中的一些更改而沒有問題。 可悲的是，沒有簡單的方法可以避免檢查它們：從一個 linux-next 版本二分查詢到更高版本（例如在“next-20241020”和“next-20241021”之間）是不可能的，因為它們沒有共同的歷史記錄。

其他閱讀材料