Git
英文 ▾ 主題 ▾ 最新版本 ▾ SubmittingPatches 最後更新於 2.46.0

準則

以下是一些回饋到此專案的準則。 還有一個 逐步教學 可用，其中涵蓋了許多相同的準則。

一個典型的補丁系列生命週期

為了幫助我們了解文件中稍後給出的各種準則背後的理由，首先讓我們了解此專案典型補丁系列的生命週期是如何進行的。

  1. 您產生了一個需求。 您將其編碼完成。 您不需要專案的任何預先授權即可執行此操作。

    您的補丁將由郵件列表上的其他貢獻者審閱，並且將進行審閱以評估各種事物的優點，例如您的補丁背後的總體想法（包括「首先，它是否正在解決一個值得解決的問題？」），解決方案設計背後的理由以及實際實作。 此處給出的準則是為了幫助您的補丁，使其更容易被審閱者理解。

  2. 您將補丁發送到列表，並抄送可能需要了解此變更的人員。 您的目標不一定是說服其他人您正在建構的東西是好的。 您的目標是獲得幫助，以便提出比您單獨建構更好的「需求」解決方案。

    可能需要了解的人員是那些處理您正在接觸的程式碼的人員。 這些人碰巧是最有可能具備足夠知識來幫助您的人，但他們沒有義務幫助您（即您請求他們的幫助，而不是要求）。 git log -p -- $area_you_are_modifying 將幫助您找出他們是誰。

  3. 您會收到關於改進的意見和建議。 您甚至可能會以「在您的變更之上」的補丁形式收到它們。 您應該在準備更新的補丁集時，在郵件列表上使用「全部回覆」來回覆它們，同時考慮它們。

  4. 潤飾、精煉，然後將您的補丁重新發送到列表以及那些花時間改進您的補丁的人員。 回到步驟（2）。

  5. 當以上迭代改進您的補丁時，維護者可能會從列表中挑選補丁，並將其排隊到 seen 分支，以便人們更容易地使用它，而不必自己挑選並將補丁應用到他們的樹狀結構中。 位於 seen 中沒有其他意義。 具體而言，這並不表示該補丁以任何方式被「接受」。

  6. 當討論達成共識，認為最新迭代的補丁狀況良好時，維護者會將該主題納入每週幾次發送到郵件列表的「What’s cooking」報告中，並標記為「將合併到 next」。 此決定主要由維護者在參與審閱討論的人員的協助下做出。

  7. 將補丁合併到 next 分支後，討論仍然可以繼續，以透過在頂部添加更多補丁來進一步改進它們，但是當一個主題合併到 next 時，預期每個人都同意該主題的範圍和基本方向是適當的，因此此類增量更新僅限於小的更正和潤飾。 在一個主題在 next 中經過一段時間（例如 7 個日曆天）而不需要在其之上進行進一步調整之後，它會被合併到 master 分支，並等待成為下一個主要版本的一部分。

在以下各節中，列出了許多技術和慣例，以幫助您的補丁在此類生命週期中有效地進行審閱。

選擇起點。

作為初步步驟，您必須首先為您的工作選擇一個起點。 通常，這表示選擇一個分支，儘管從技術上講，它實際上是一個特定的提交（通常是分支的 HEAD 或提示）。

有幾個重要的分支需要注意。 也就是說，如 gitworkflows[7] 中所述，有四個整合分支

  • maint

  • master

  • next

  • seen

清單中較低的分支通常是其先前分支的後代。 例如，maint 是比 master 「舊」的分支，因為 master 通常在 maint 之上有補丁（提交）。

還有「主題」分支，其中包含來自其他貢獻者的工作。 主題分支由 Git 維護者（在其 fork 中）建立，以組織郵件列表上目前的一組傳入貢獻，並在定期的「git.git 中的新進展」公告中逐條列出。 若要尋找主題分支的提示，請執行 git log --first-parent master..seen 並尋找合併提交。 此提交的第二個父級是主題分支的提示。

選擇正確起點的一個指導原則是：一般而言，始終以您的變更所相關的最舊整合分支為基礎（請參閱 gitworkflows[7] 中的「向上合併」）。 此原則的含義是，在絕大多數情況下，新工作的起點應該是 maint 或 master 的最新 HEAD 提交，依據以下情況：

  • 如果您正在修復已發布版本中的錯誤，請使用 maint 作為起點（這可能表示您必須在不使用最近出現在 master 中但在已發布版本中不可用的最新 API 功能的情況下修復錯誤）。

  • 否則（例如，如果您正在新增新功能）請使用 master。

注意
 在特殊情況下，舊版本中引入的錯誤可能必須為比最近版本舊得多的版本的用戶修復。 git describe --contains X 可能將提交 X 的 X 描述為 v2.30.0-rc2-gXXXXXX，該提交引入了該錯誤，並且該錯誤可能影響非常大，以至於我們可能需要針對 Git 2.30.x 系列發布新的維護版本，而「Git 2.41.0」是當前版本。 在這種情況下，您可能需要使用 2.30.x 系列的維護分支的提示，該提示可能在 維護者的「分拆」儲存庫 中的 maint-2.30 分支中可用。

這也表示，如果您希望您的工作有實際機會晉升到 master，則 next 或 seen 是不適當的工作起點。 它們根本不是設計為用作新工作的基礎；它們僅用於確保正在進行中的主題可以很好地協同工作。 這就是為什麼 next 和 seen 都會頻繁地與郵件列表中的傳入補丁重新整合，並強制推送以替換其先前的版本。 如果一個主題實際上建立在 next 之上，則在不引入 next 中的所有其他主題（其中一些可能尚未準備好）的情況下，無法將其合併到 master。

例如，如果您正在進行樹狀結構範圍內的變更，而其他人也在進行他們自己的樹狀結構範圍內的變更，則您的工作可能與其他人的工作嚴重重疊。 這種情況可能會讓您想使用 next 作為起點（因為它會包含其他人的工作），但是這樣做表示您不僅會依賴其他人的工作，還會依賴已整合到 next 中的其他貢獻者的所有其他隨機事物。 而且，一旦 next 使用新版本更新，您所有工作都將需要進行重新定基，以便維護者可以乾淨地應用它們。

在極特殊的情況下，您絕對必須依賴 next 中但不在 master 中的少數選定主題分支，您可以透過 fork master 並將所需的主題分支合併到其中來建立自己的自訂基礎分支。 然後，您可以在此基礎分支之上工作。 但是請記住，此基礎分支僅為您私下所知。 因此，當您準備將補丁發送到列表時，請務必在您的封面信中說明您是如何建立它的。 此關鍵資訊將允許其他人在其終端上重新建立您的基礎分支，以便他們可以試用您的工作。

最後，請注意，系統的某些部分有專門的維護者，他們有自己的獨立原始碼儲存庫（請參閱以下「子系統」部分）。

針對邏輯上獨立的變更建立獨立的提交。

除非您的修補程式非常簡單，否則您不應該發送工作目錄與提交頭之間產生的修補程式。相反地，請務必建立包含完整提交訊息的提交，並從您的儲存庫產生一系列修補程式。這是一個良好的習慣。

請詳細解釋變更，以便人們可以判斷是否值得進行，而無需閱讀實際的修補程式文字來確定程式碼是否符合解釋中所承諾的功能。

如果您的描述開始變得太長，這表示您可能需要將提交拆分成更細的粒度。話雖如此，清楚描述有助於審閱者檢查修補程式以及未來維護者理解程式碼的修補程式，才是最棒的修補程式。描述可以很好地總結主題重點，並說明變更的動機、採用的方法，以及（如果相關）與先前版本的主要差異，這些都是很好的做法。

請確保您有針對您正在修復的錯誤的測試。有關指南，請參閱 t/README。

新增功能時，請確保您有新的測試來顯示該功能在應該觸發時觸發新行為，並顯示該功能在不應該觸發時不會觸發。在任何程式碼變更之後，請確保整個測試套件通過。修復錯誤時，請確保您有新的測試，如果其他人意外破壞您修復的內容，測試會失敗，以避免迴歸。此外，請嘗試將您的工作合併到 *next* 和 *seen*，並確保測試仍然通過；其他人的主題仍在進行中，可能會與您在主題中嘗試執行的操作產生意外的互動。

推送到 https://github.com/git/git 的分支會使用他們的 CI 整合在 Linux、Mac 和 Windows 上測試您的變更。詳情請參閱 GitHub CI 章節。

不要忘記更新文件以描述更新後的行為，並確保產生的文件集格式良好（嘗試 Documentation/doc-diff 腳本）。

我們目前對於拼寫和語法混合使用美式和英式英語規範，這有點不幸。但一個大幅修補程式為了修正不一致之處而觸及各處檔案是不受歡迎的。這種修補程式可能導致的與其他變更的潛在衝突是不值得的。我們傾向於逐步調和這些不一致之處，轉向美式英語，以小型且易於理解的修補程式，作為在附近進行其他實際工作時的副作用（例如，為了清楚起見而重寫一段文字，同時將英式英語拼寫改為美式英語）。明顯的排版修正更受歡迎（「teh → 「the」」），最好作為獨立的修補程式提交，與其他文件變更分開。

哦，還有一件事。我們對空白字元很挑剔。請確保您的變更不會觸發 templates/hooks--pre-commit 中隨附的範例 pre-commit hook 的錯誤。為了確保不會發生這種情況，請在提交之前對您的變更執行 git diff --check。

好好描述您的變更。

解釋您變更的日誌訊息與變更本身同等重要。您的程式碼可以使用程式碼內的註解清楚地撰寫，以充分解釋它如何與周圍的程式碼一起運作，但未來需要修復或增強您的程式碼的人員需要知道您的程式碼為什麼這樣做，原因如下：

  1. 您的程式碼可能執行的動作與您想要執行的動作不同。寫下您實際想要達成的目標將有助於他們修復您的程式碼，並使其執行應有的功能（此外，您通常在撰寫日誌訊息以總結其背後的想法時，會發現自己的錯誤）。

  2. 您的程式碼可能僅為您當前的需求執行必要的動作（例如，「對目錄執行 X」，而沒有實作或甚至設計要對檔案執行的動作）。寫下您為什麼排除程式碼未執行的動作將有助於指導未來的開發人員。寫下「我們對目錄執行 X，因為目錄具有特性 Y」將有助於他們推斷「哦，檔案也具有相同的特性 Y，所以對它們執行 X 可能也很有意義？」。說明「我們不對檔案執行相同的 X，因為...」將有助於他們決定推理是否合理（在這種情況下，他們不會浪費時間擴展您的程式碼以涵蓋檔案），或者以不同的方式推理（在這種情況下，他們可以解釋為什麼他們也擴展您的程式碼以涵蓋檔案）。

您的日誌訊息的目標是傳達變更背後的原因，以協助未來的開發人員。審閱者也會確保您建議的日誌訊息能夠很好地達到此目的。

提交訊息的第一行應該是簡短描述（軟限制為 50 個字元，請參閱 git-commit[1] 中的討論），並且應該省略句點。在大多數情況下，也習慣在第一行加上「area: 」前綴，其中 area 是正在修改的程式碼的一般區域的檔案名稱或識別碼，例如：

  • doc: 澄清簽署和 pgp 簽名的區別

  • githooks.txt: 改善介紹部分

如果您不確定要使用哪個識別碼，請在您正在修改的檔案上執行 git log --no-merges 以查看目前的慣例。

在「area:」前綴之後的標題句子省略結尾句點，且其第一個字不會大寫（省略大寫僅適用於標題的「area:」前綴之後的字），除非有理由將其大寫，而不是因為它是句子中的第一個字。例如，「doc: 澄清…​」，而不是「doc: Clarify…​」，或「githooks.txt: 改善…​」，而不是「githooks.txt: Improve…​」。但「refs: HEAD 也被視為 ref」是正確的，因為即使 HEAD 出現在句子中間，我們也會將其全部大寫。

內文應提供有意義的提交訊息，該訊息

  1. 解釋變更嘗試解決的問題，即沒有變更時目前程式碼的問題。

  2. 證明變更解決問題的方式是合理的，即變更後的結果為何更好。

  3. 如果有的話，列出考慮但被捨棄的替代解決方案。

描述現狀的問題陳述是以現在時態撰寫的。寫「程式碼在給定輸入 Y 時執行 X」，而不是「程式碼在給定輸入 X 時曾經執行 Y」。您不必說「目前」---根據專案慣例，問題陳述中的現狀是關於沒有變更的程式碼。

以祈使語氣描述您的變更，例如「使 xyzzy 執行 frotz」，而不是「[此修補程式] 使 xyzzy 執行 frotz」或「[我] 變更 xyzzy 以執行 frotz」，就好像您正在命令程式碼庫變更其行為一樣。盡量確保您的解釋可以在沒有外部資源的情況下被理解。不要提供郵件清單存檔的 URL，而是總結討論的相關重點。

您可能希望在歷史記錄的「較穩定」部分（即在 maint、master 和 next 等分支上）參考另一個提交的原因有幾個：

  1. 引入您正在修復的錯誤的根本原因的提交。

  2. 引入您正在增強的功能的提交。

  3. 當您將您的工作試合併到 next 和 seen 以進行測試時，與您的工作發生衝突的提交。

當您在較穩定的分支（例如 master、maint 和 next）上參考提交時，請使用「縮寫雜湊值（主旨，日期）」格式，如下所示：

	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
	noticed that ...

gitk 的「複製提交參考」命令可用於取得此格式（主旨括在一對雙引號中），或使用 git show 的此調用：

	git show -s --pretty=reference <commit>

或者，在不支援 --pretty=reference 的舊版 Git 上：

	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>

透過新增您的 Signed-off-by 尾碼來證明您的工作

為了改進對誰做了什麼的追蹤，我們要求您透過「簽署」您的修補程式，證明您撰寫了修補程式，或有權以與我們相同的授權傳遞它。沒有簽署，我們無法接受您的修補程式。

如果您（且僅在您）證明下方的 D-C-O

開發人員原始碼憑證 1.1

透過對此專案做出貢獻，我證明

  1. 貢獻的全部或部分是由我建立的，並且我有權根據檔案中指示的開放原始碼授權提交它；或

  2. 該貢獻是基於先前的工作，據我所知，該工作已涵蓋在適當的開放原始碼授權下，並且我有權根據該授權提交該經過修改的工作，無論其全部或部分由我建立，均以相同的開放原始碼授權（除非我被允許以不同的授權提交），如檔案中所示；或

  3. 該貢獻是由其他人員直接提供給我的，該人員證明了 (a)、(b) 或 (c)，並且我沒有修改它。

  4. 我理解並同意此專案和貢獻是公開的，並且貢獻記錄（包括我提交的所有個人資訊，包括我的簽署）會無限期地保留，並且可能會根據此專案或相關的開放原始碼授權重新發布。

您在提交中新增一個「Signed-off-by」尾碼，如下所示：

	Signed-off-by: Random J Developer <random@developer.example.org>

如果您使用 -s 選項執行 git-commit 命令，則 Git 可以新增此行。

請注意，當您轉發其他人的修補程式時，可以使用上述 D-C-O 規則放置您自己的 Signed-off-by 尾碼。事實上，我們鼓勵您這樣做。不要忘記在開頭放置內文「From:」行，以正確地將變更歸於其真正的作者（請參閱上方的 (2)）。

此程序最初來自 Linux 核心專案，因此我們的規則與他們的規則非常相似，但是簽署您的修補程式的確切含義因專案而異，因此可能與您習慣的專案不同。

另請注意，Signed-off-by 尾碼中使用的是真實姓名。請不要隱藏您的真實姓名。

如果您願意，您可以在結尾處放置額外的標籤：

  1. Reported-by: 用於表彰發現修補程式嘗試修復的錯誤的人。

  2. Acked-by: 表示更熟悉修補程式嘗試修改的區域的人員喜歡該修補程式。

  3. 與其他標籤不同，Reviewed-by: 只能由審閱者在詳細分析後對修補程式完全滿意時提供。

  4. Tested-by: 用於表示人員套用了修補程式，並發現它具有預期的效果。

  5. Co-authored-by: 用於表示人員在提交修補程式之前交換了修補程式草稿。

  6. Helped-by: 用於感謝那些提出修改想法，但未提供精確修改程式碼的人。

  7. Mentored-by: 用於感謝那些在指導計畫（例如：GSoC 或 Outreachy）中協助開發程式碼的人。

  8. Suggested-by: 用於感謝那些提出程式碼修改想法的人。

雖然您也可以在情況需要時建立自己的註腳（trailer），但我們鼓勵您使用本專案中上述的通用註腳。

標籤（tags）的首字母應大寫，例如使用 "Signed-off-by" 而非 "Signed-Off-By"，以及 "Acked-by:" 而非 "Acked-By"。

使用 Git 工具從您的提交（commits）中產生程式碼修補（patch）。

基於 Git 的差異工具會產生統一差異（unidiff）格式，這是首選格式。

如果您的程式碼修補包含檔案重新命名，請不用害怕使用 git diff 或 git format-patch 的 -M 選項。接收端可以正確處理它們。

請確保您的程式碼修補未加入註解掉的除錯程式碼，或包含任何與您的程式碼修補目標無關的額外檔案。產生程式碼修補後，請務必檢查以確保準確性。在發送之前，請確保它能乾淨地應用到您在「選擇起點」章節中選擇的起點。

注意
 從審閱您程式碼修補的人的角度來看，master 分支是預期的預設起點。因此，如果您選擇了不同的起點，請在您的封面信中說明此選擇。

發送您的程式碼修補。

選擇您的審閱者

注意
 可能與安全性相關的程式碼修補應私下提交至 Git 安全性郵件列表[1]，而不是公開的郵件列表。

發送您的程式碼修補時，「To:」設定為郵件列表，「cc:」列出參與您所修改區域的人員（contrib/contacts/ 中的 git-contacts 腳本[2]可以幫助您識別他們），以徵求意見和審閱。此外，當您將主題試合併到 next 和 seen 時，您可能已注意到其他人的工作與您的更改衝突。這些人很有可能很了解您所修改的區域。

如果您使用 send-email，您可以像這樣將 git-contacts 的輸出提供給它

	git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch

在列表達成共識認為應用程式碼修補是個好主意後，重新發送它，「To:」設定為維護者[3]，「cc:」郵件列表[4] 以包含進去。當維護者沒有大量參與討論，而是將審閱工作交給信任的其他人時，這尤其重要。

不要忘記根據需要添加諸如 Acked-by:、Reviewed-by: 和 Tested-by: 之類的註腳，以感謝幫助您程式碼修補的人員，並在發送此最終版本以包含進去時「cc:」他們。

format-patch 和 send-email

如果可以，請學習使用 format-patch 和 send-email。這些命令針對發送程式碼修補的工作流程進行了最佳化，避免了您現有的電子郵件客戶端（通常針對「multipart/*」MIME 類型電子郵件進行最佳化）可能會使您的程式碼修補無法使用的許多方式。

注意
 在這裡，我們概述了使用 format-patch 和 send-email 的步驟，但您也可以使用 GitGitGadget 來發送您的程式碼修補（請參閱 MyFirstContribution）。

Git 郵件列表中的人員需要能夠閱讀並評論您提交的變更。開發人員能夠使用標準電子郵件工具「引用」您的變更，以便他們可以評論您程式碼的特定部分，這點非常重要。因此，每個程式碼修補應以單獨訊息中的「內嵌」方式提交。

程式碼修補系列的所有後續版本和其他相關程式碼修補應分組到它們自己的電子郵件線程中，以幫助讀者找到系列的所有部分。為此，請將它們作為對額外的「封面信」訊息（請參閱下文）、第一個程式碼修補或各自先前程式碼修補的回覆發送。這是關於如何提交程式碼修補系列的更新版本的逐步指南。

如果您的日誌訊息（包括 Signed-off-by 註腳中的名稱）無法以 ASCII 寫入，請確保您以正確的編碼發送訊息。

警告
 請注意您的 MUA（郵件使用者代理）的自動換行可能會損壞您的程式碼修補。請勿複製貼上您的程式碼修補；如果您不小心，可能會因此遺失 Tab 鍵。

在主旨行前加上 [PATCH] 是一種常見的慣例。這讓大家可以輕鬆區分程式碼修補與其他電子郵件討論。也鼓勵在方括號中使用 PATCH 以外的標記來描述程式碼修補的性質。例如，[RFC PATCH]（其中 RFC 代表「請求評論」）通常用於表示程式碼修補在被接受之前需要進一步討論，[PATCH v2]、[PATCH v3] 等通常會在您發送先前發送的更新時看到。

git format-patch 命令遵循目前最佳實務來格式化電子郵件訊息的內文。程式碼修補的開頭應是您的提交訊息，以 Signed-off-by 註腳結尾，以及由三個破折號組成的行，然後是差異統計資訊和程式碼修補本身。如果您是轉發其他人的程式碼修補，您可以選擇在電子郵件訊息的開頭、提交訊息開始之前，加上「From: 」行來命名該人員。若要將主旨中的預設「[PATCH]」變更為「[<text>]」，請使用 git format-patch --subject-prefix=<text>。作為快捷方式，您可以使用 --rfc 代替 --subject-prefix="RFC PATCH"，或使用 -v <n> 代替 --subject-prefix="PATCH v<n>"。

您通常希望新增關於程式碼修補的額外說明，而不是提交訊息本身。請將此類「封面信」材料放置在三條破折號線和差異統計資料之間。對於需要多次審閱和討論的程式碼修補，每次迭代之間的變更說明可以保留在 Git 筆記中，並透過 git format-patch --notes 在三條破折號線後自動插入。

這是實驗性的.

當發送主題時，您可以提出一個段落摘要，當該摘要被選取來解釋該主題時，應出現在「最新進展」報告中。如果您選擇這樣做，請寫一段 2-5 行的段落，該段落將很適合我們的發行說明（請參閱 Documentation/RelNotes/* 檔案中的許多項目符號條目作為範例），並使其成為封面信的第一段。對於單一程式碼修補系列，請使用三條破折號線和差異統計資料之間的空間，如前所述。

請勿將程式碼修補作為 MIME 附件附加，無論是否壓縮。請勿讓您的電子郵件客戶端發送 quoted-printable。請勿讓您的電子郵件客戶端發送 format=flowed，這會破壞程式碼修補中的空白。許多常用的電子郵件應用程式並非總是會將 MIME 附件作為純文字傳輸，這使得無法評論您的程式碼。MIME 附件也需要花費更多時間處理。這並不會降低您的 MIME 附件變更被接受的可能性，但這會使它更有可能被延遲。。

例外情況：如果您的郵件程式正在損壞程式碼修補，那麼可能會有人要求您使用 MIME 重新發送它們，這沒問題。

請勿使用 PGP 簽署您的程式碼修補。大多數情況下，您的維護者或列表上的其他人不會擁有您的 PGP 金鑰，也不會費心去取得它。您的程式碼修補並不是根據您是誰來判斷；來自未知來源的良好程式碼修補比來自已知、受人尊敬的來源，但做得不好或做錯事情的程式碼修補，有更好的機會被接受。

如果您真的真的真的非常想要執行 PGP 簽署的程式碼修補，請將其格式化為「multipart/signed」，而不是以 -----BEGIN PGP SIGNED MESSAGE----- 開頭的 text/plain 訊息。那不是 text/plain，而是其他東西。

處理衝突和迭代程式碼修補

當修改對您的程式碼修補所做的變更時，請務必確認與其他正在進行的主題發生衝突的可能性。為了有效地處理這些潛在的衝突，請遵循下面概述的建議步驟

  1. 在合適的基礎分支上建置，請參閱上方的章節，並格式化程式碼修補系列。如果您正在執行「rebase -i」就地更新前一輪，這將重複使用先前的基礎，因此 (2) 和 (3) 可能會變得微不足道。

  2. 尋找上一輪已加入佇列的基礎位置

    $ mine='kn/ref-transaction-symref'
$ git checkout "origin/seen^{/^Merge branch '$mine'}...master"

  3. 應用程式碼修補的格式化結果。有兩種情況

    1. 所有內容都乾淨地應用並且測試正常。跳到 (4)。

    2. 所有內容都乾淨地應用，但無法建置或測試失敗，或者所有內容未乾淨地應用。

      在後一種情況下，您會有來自舊基礎和您在 (1) 中用來建置的基礎之間差異的文字或語意衝突。找出導致錯誤的原因（例如，自 (2) 使用的基礎到 (1) 使用的基礎以來，可能已合併一兩個主題）。

      檢查最新的 origin/master（可能比 (2) 使用的基礎新），在那裡「merge --no-ff」您新依賴的主題，並使用合併結果作為基礎，重新建置系列並再次測試。從最後一次此類合併到您的主題提示執行 format-patch。如果您這樣做

      $ git checkout origin/master
$ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar
$ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux
... rebuild the topic ...

      那麼您只需在這些「準備基礎」合併之上格式化您的主題，例如

      $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD

      不要忘記在封面信中寫下您這樣做的內容，包括您在 master 之上基礎中的主題。然後跳到 (4)。

  4. 將您的主題試合併到 next 和 seen 中，例如

    $ git checkout --detach 'origin/seen'
$ git revert -m 1 <the merge of the previous iteration into seen>
$ git merge kn/ref-transaction-symref

    如果您的主題的先前迭代已在 seen 中（如本例所示），則需要「revert」。您可以選擇從頭開始重新建置 master..origin/seen，同時排除您先前的迭代，這可能更密切地模擬維護者端的狀況。

    此試合併可能會發生衝突。它主要是為了查看其他主題可能與您的主題發生什麼衝突。換句話說，您不必依賴它來使您的主題在 master 上運作。如果您的主題在它們之前進入 next，那麼解決衝突可能會成為其他主題所有者的工作。

    在封面信中記下您看到的衝突。您不一定需要解決它們，但這將是一個很好的機會來了解其他人在相關領域正在做什麼。

    $ git checkout --detach 'origin/next'
$ git merge kn/ref-transaction-symref

    這是為了查看您的主題與其他已經在進行的主題之間存在哪些衝突。如果 (3)-2 在更新後的 master 加上從 next 取得的相依主題之上準備了基礎，那麼這應該不會衝突。除非情況嚴重（判斷方法之一是嘗試使用您的舊迭代執行相同的試合併，這可能會以類似的方式發生衝突），否則預期它會在維護者端處理（如果變得難以處理，當我收到您的程式碼修補時，我會要求重新設定基礎）。

具有專屬維護者的子系統

系統的某些部分有具有自己儲存庫的專屬維護者。

  • git-gui/ 來自 Johannes Sixt 維護的 git-gui 專案

    https://github.com/j6t/git-gui

  • gitk-git/ 來自 Paul Mackerras 的 gitk 專案

    git://git.ozlabs.org/~paulus/gitk
    Those who are interested in improving gitk can volunteer to help Paul
maintain it, cf. <YntxL/fTplFm8lr6@cleo>.

  • po/ 來自本地化協調員 Jiang Xin

    https://github.com/git-l10n/git-po/

這些部分的修補應基於它們的樹狀結構。

  • 由 Jean-Noël Avila 領導的「Git 文件翻譯」專案，負責翻譯我們的文件頁面。他們的工作成果與這個專案分開維護，不屬於我們的樹狀結構。

    https://github.com/jnavila/git-manpages-l10n/

GitHub CI

在 GitHub 上擁有帳戶後，您可以使用 GitHub CI 在 Linux、Mac 和 Windows 上測試您的變更。請參閱https://github.com/git/git/actions/workflows/main.yml 以查看最近 CI 執行的範例。

請依照下列步驟進行初始設定

  1. 將 https://github.com/git/git 分叉 (Fork) 到您的 GitHub 帳戶。您可以在這裡找到關於如何分叉的詳細說明：https://help.github.com/articles/fork-a-repo/

完成初始設定後，每當您將新的變更推送到您在 GitHub 上的 Git 分叉時，CI 都會執行。您可以在這裡監控所有分支的測試狀態：https://github.com/<您的 GitHub 帳號>/git/actions/workflows/main.yml

如果某個分支沒有通過所有測試案例，它將會被標記為紅色的 x，而不是綠色的勾號。在這種情況下，您可以點擊失敗的作業，然後導覽至 "ci/run-build-and-tests.sh" 和/或 "ci/print-test-failures.sh"。您也可以下載「Artifacts」，這些是包含經過 tar（或 zipped）壓縮的封存檔案的 zip 壓縮檔，其中包含與除錯相關的測試資料。

然後修正問題，並將您的修正推送到您的 GitHub 分叉。這將觸發新的 CI 建置，以確保所有測試都通過。

MUA 相關提示

我從列表接收或選取的一些修補程式，都有常見的損壞模式。請確保您的 MUA 設定正確，以避免損壞空白字元。

請參閱 git-format-patch[1] 的 DISCUSSION 章節，以取得關於將修補程式郵寄給自己並使用 git-am[1] 應用修補程式的提示。

在您進行此操作時，請檢查試執行應用修補程式後的產生的提交日誌訊息。如果產生的提交內容與您希望看到的內容不完全一致，那麼您的維護人員很可能會在應用您的修補程式時手動編輯日誌訊息。如果您真的想在修補程式電子郵件中放入「嗨，這是我的第一個修補程式。\n」之類的內容，則應該放在標示提交訊息結束的三條破折線之後。

Pine

(Johannes Schindelin)

I don't know how many people still use pine, but for those poor
souls it may be good to mention that the quell-flowed-text is
needed for recent versions.

... the "no-strip-whitespace-before-send" option, too. AFAIK it
was introduced in 4.60.

(Linus Torvalds)

And 4.58 needs at least this.

diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
Author: Linus Torvalds <torvalds@g5.osdl.org>
Date:   Mon Aug 15 17:23:51 2005 -0700

    Fix pine whitespace-corruption bug

    There's no excuse for unconditionally removing whitespace from
    the pico buffers on close.

diff --git a/pico/pico.c b/pico/pico.c
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
	    switch(pico_all_done){	/* prepare for/handle final events */
	      case COMP_EXIT :		/* already confirmed */
		packheader();
+#if 0
		stripwhitespace();
+#endif
		c |= COMP_EXIT;
		break;

(Daniel Barkalow)

> A patch to SubmittingPatches, MUA specific help section for
> users of Pine 4.63 would be very much appreciated.

Ah, it looks like a recent version changed the default behavior to do the
right thing, and inverted the sense of the configuration option. (Either
that or Gentoo did it.) So you need to set the
"no-strip-whitespace-before-send" option, unless the option you have is
"strip-whitespace-before-send", in which case you should avoid checking
it.

Thunderbird、KMail、GMail

請參閱 git-format-patch[1] 的 MUA-SPECIFIC HINTS 章節。

Gnus

*Summary* 緩衝區中的「|」可用於將目前訊息傳送到外部程式，這是驅動 git am 的便捷方式。但是，如果訊息是 MIME 編碼的，則傳送到程式中的內容是您在解開 MIME 後在 *Article* 緩衝區中看到的表示方式。這通常不是您想要的，原因有二。它容易搞亂非 ASCII 字元（最明顯的是人們的名字），也容易搞亂空白字元（在修補程式中是致命的）。在執行管道之前，執行 "C-u g" 以原始格式顯示訊息可以解決此問題。

1. Git 安全性郵件列表：git-security@googlegroups.com
2. `contrib/` 下的腳本不是核心 `git` 二進位檔的一部分，必須直接呼叫。複製 Git 程式碼庫並執行 `perl contrib/contacts/git-contacts`。
3. 目前的維護人員：gitster@pobox.com
4. 郵件列表：git@vger.kernel.org
scroll-to-top