文檔專用PR批量合併 是做什麼的？
概述
將許多小型文檔拉取請求合併為一個批次進行審查會更有效率。本程序將多個已審查、僅限文檔的拉取請求中的檔案複製到一個新的草稿拉取請求中，每個來源請求對應一個提交。檔案內容會被精確複製，不做任何編輯。來源拉取請求保持不變。審查者隨後合併此批次拉取請求，而來源拉取請求會根據其自身狀態關閉，不經由此程序的任何操作。
使用時機
- 多個開啟的文檔拉取請求已通過審查，且每個請求僅觸及文檔路徑。
- 審查者要求將它們整合到一個拉取請求中。
請勿將其用於程式碼、配置，或用於任何尚未通過審查的來源拉取請求。
功能特色
- 使用暫存工作樹，因此不會影響目前的工作目錄。
- 對每個來源拉取請求的狀態、基底分支、頭部提交和檔案列表進行即時快照，並與已獲取的頭部提交進行比對。
- 對已關閉、觸及文檔資料夾外部路徑、與主分支衝突、或與其他開啟拉取請求衝突的請求，設有跳過規則。
- 每個合併的來源對應一個提交，並設有斷言，當來源有問題時會停止運行。
- 在推送前對變更路徑進行檢查，以及一個驗證區塊，用於比對每個檔案的 blob 與其來源頭部。
優勢
- 有問題的來源會中止運行，而不是部分合併。
- 每個合併的檔案內容都證明與其來源相同。
- 跳過的拉取請求會列出原因，因此不會無聲無息地遺漏任何項目。
- 批次拉取請求以草稿模式開啟，因此最終決定權在審查者手中。
程序
-
在暫存工作樹中工作。 獲取主分支和來源拉取請求的頭部，然後在主分支上於暫存資料夾中建立一個新分支：
git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*' git worktree add -b <batch-branch> <scratch-dir>/wt origin/main如果 HTTPS 獲取或推送因驗證失敗，請對該命令使用程式碼託管平台的 CLI 作為憑證助手來運行，例如
-c credential.helper= -c 'credential.helper=!gh auth git-credential'。請勿變更已儲存的配置，也請勿列印 token。 -
即時快照一次。 對於每個來源拉取請求，讀取其狀態、草稿標記、基底分支、頭部提交和檔案列表。同時列出開啟的拉取請求以進行衝突檢查。斷言每個來源的頭部提交等於已獲取的
refs/remotes/origin/pr/<n>提交。 -
決定跳過或合併，按編號順序進行。 如果滿足以下任一條件，則跳過該拉取請求並記錄原因：
- 它不是「開啟」狀態。
- 其任何路徑位於文檔資料夾之外。
- 其任何路徑已存在於主分支上。對於已存在於主分支的路徑，比較它的 blob。內容相同表示已早先合併。內容不同則需要重新基底。
- 另一個開啟的拉取請求變更了其任何路徑。
-
將每個拉取請求作為一個提交合併。 對於每個合併的拉取請求，從其頭部提交中檢出檔案，並使用包含該拉取請求編號的訊息提交它們。在一個迴圈中運行此操作，該迴圈會斷言拉取請求是開啟的、頭部匹配、路徑位於文檔資料夾下，且均未出現在主分支上。斷言失敗會中止運行。
git checkout <head-commit> -- <paths> git commit -m "docs: land #<n>" -
在推送前檢查變更。 文檔資料夾之外的變更檔案數量必須為零。變更檔案的總數必須等於每個來源拉取請求的路徑計數總和。
-
建立驗證區塊。 對於每個拉取請求及其每個路徑，比較批次分支
HEAD上的 blob 與來源頭部的 blob。為每個拉取請求列印一行，顯示其頭部、路徑計數、blob 計數和MATCH，再加上總計。將該區塊原樣貼入批次拉取請求的描述中。 -
以草稿模式開啟批次拉取請求。 推送分支，然後針對主分支建立一個草稿。標題應說明實際合併的拉取請求數量，而非考慮的數量：
gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file> -
編寫描述。 包含一則說明，指出因為是僅文檔差異而跳過建置、已合併的拉取請求列表（含檔案計數和頭部）、跳過的拉取請求及其原因、給審查者的任何標記，以及驗證區塊。重新讀取新拉取請求的狀態，並確認它是針對主分支的草稿。
常見陷阱
- 忽略草稿規則。 某次運行的指令可能要求建立一個「準備審查」的拉取請求。除非運行規則另有說明，否則請以草稿模式開啟，並在描述中說明。
- 來源拉取請求基於另一個分支。 其檔案通過了所有路徑規則，但將它們合併到主分支會改變該拉取請求的意義。僅在規則允許的情況下才包含它，並用確切的待丟棄提交進行標記。
- 無合併基底。 此類拉取請求的合併基底查找可能失敗，而與基底進行差異比較時會出錯。請使用即時檔案列表作為路徑來源。僅在存在合併基底時，才與其交叉檢查差異。
- 部分合併。 一個修改了主分支上已有檔案的拉取請求，即使其其他檔案是新的，也可能被跳過。請勿部分合併它。
- 以遺失路徑錯誤淹沒輸出。 檢查路徑是否存在於主分支時，每個遺失的路徑都會印出一個錯誤。在這些檢查中，請將標準錯誤重新導向到
/dev/null。 - 填充最終報告。 報告中列出跳過的列表及其原因、標記和驗證總計。請勿列出每個檔案。
- 缺失的圖形或索引。 如果儲存庫的程式碼智能索引不可用，請在報告中說明，並且不要跳過路徑規則。
驗證
- 批次拉取請求是針對主分支的草稿。
- 每個合併的檔案的 blob 與其來源頭部匹配，如驗證區塊所示。
- 沒有變更的檔案位於文檔資料夾之外。
- 每個跳過的拉取請求在描述中都有一個原因。
- 來源拉取請求保持不變。此程序未對它們進行合併、批准、關閉或評論。