簡體中文 ▾ 主題 ▾ 最新版本 ▾ SubmittingPatches 最後更新於 2.48.0

此資訊專用於 Git 專案

請注意，如果您打算為 Git 專案本身做貢獻，此資訊才與您相關。它絕不是普通 Git 使用者的必讀內容。

指南

以下是為此專案貢獻的一些指南。另有一個分步教程，涵蓋了許多相同的指南。

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

為了幫助我們理解文件後面給出的各種指南背後的原因，首先讓我們瞭解此專案典型補丁系列的生命週期是怎樣的。

  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] 中討論了四個整合（integration）分支

  • maint

  • master

  • next

  • seen

列表中靠後的分支通常是其前面分支的後代。例如，maint 是比 master “更舊”的分支，因為 master 通常包含在 maint 之上的補丁（提交）。

還有“主題”分支（topic branches），其中包含其他貢獻者的工作。主題分支由 Git 維護者（在其派生倉庫中）建立，用於組織郵件列表中當前收到的貢獻集，並在定期釋出的“git.git 正在進行中”公告中列出。要查詢主題分支的尖端（tip），執行 git log --first-parent master..seen 並查詢合併提交。此提交的第二個父提交是主題分支的尖端。

選擇正確起點有一條指導原則：通常，你的工作應始終基於與你的更改相關的最舊的整合（integration）分支（參見 gitworkflows[7] 中的“向上合併”）。這條原則意味著，絕大多數情況下，新工作的起點應該是 maint 或 master 的最新 HEAD 提交，具體取決於以下情況：

  • 如果你正在修復已釋出版本中的錯誤，請使用 maint 作為起點（這可能意味著你必須在不使用 master 中最近出現但未在已釋出版本中可用的最新 API 功能的情況下進行修復）。

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

注意
 在特殊情況下，對於比最近釋出版本舊得多的版本使用者，可能需要修復在舊版本中引入的錯誤。git describe --contains X 可能會將引入該錯誤的提交 X 描述為 v2.30.0-rc2-gXXXXXX，並且該錯誤的影響可能如此之大，以至於在“Git 2.41.0”是當前釋出版本時，我們可能需要為 Git 2.30.x 系列釋出新的維護版本。在這種情況下，你可能希望使用 2.30.x 系列維護分支的尖端，這可能在維護者的“獨立”倉庫中的 maint-2.30 分支中可用。

這也意味著，如果你希望你的工作有實際機會晉級到 master，那麼 next 或 seen 不適合作為你工作的起點。它們根本不是為了用作新工作的基礎而設計的；它們只是為了確保正在進行的主題能夠很好地協同工作。這就是為什麼 next 和 seen 經常與郵件列表中收到的補丁重新整合，並被強制推送以替換它們自己的先前版本。一個完全建立在 next 之上的主題不能在不將 next 中所有其他主題（其中一些可能尚未準備好）拖入的情況下合併到 master。

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

在真正特殊的情況下，如果你絕對必須依賴 next 中已有但 master 中沒有的少數幾個主題分支，你可能希望透過派生 master 並將所需的主題分支合併到其中來建立自己的自定義基礎分支。然後你可以在這個基礎分支之上進行工作。但請記住，這個基礎分支只對你私有。因此，當你準備將補丁傳送到列表時，請務必在你的附函中說明你是如何建立它的。這一關鍵資訊將允許他人在他們那邊重新建立你的基礎分支，以便他們嘗試你的工作。

最後，請注意系統的某些部分有專門的維護者，他們擁有自己的獨立原始碼倉庫（參見下面的“子系統”部分）。

為邏輯上獨立的更改建立單獨的提交。

除非你的補丁確實微不足道，否則你不應該傳送工作樹和提交頭之間生成的補丁。相反，始終建立一個包含完整提交訊息的提交，並從你的倉庫生成一系列補丁。這是一種良好的規範。

為更改提供足夠詳細的解釋，以便人們可以在不閱讀實際補丁文字的情況下判斷它是否是件好事，以確定程式碼是否很好地實現瞭解釋所承諾的功能。

如果你的描述開始變得太長，這表明你可能需要將提交拆分為更細粒度的部分。話雖如此，那些清晰描述有助於審閱者檢查補丁和未來維護者理解程式碼的事項的補丁，是最美觀的補丁。在主題中很好地總結要點，並描述更改的動機、更改所採取的方法，以及（如果相關）這與先前版本有何實質性不同的描述，都是值得擁有的好東西。

確保你為正在修復的 bug 編寫了測試。請參閱 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 鉤子的錯誤。為了幫助確保不會發生這種情況，在提交之前對你的更改執行 git diff --check。

清晰地描述你的更改。

解釋你更改的日誌訊息與更改本身同等重要。你的程式碼可能編寫清晰，並帶有程式碼內註釋，足以解釋它如何與周圍程式碼協同工作，但未來需要修復或增強你的程式碼的人將需要知道你的程式碼為何這樣做，原因如下：

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

  2. 你的程式碼可能正在執行僅為滿足你當前需求所需的操作（例如，“對目錄執行 X”，而未實現甚至未設計對檔案執行的操作）。寫下你為何排除程式碼未執行的操作，將有助於指導未來的開發人員。寫下“我們對目錄執行 X，因為目錄具有特性 Y”將幫助他們推斷“哦，檔案也具有相同的特性 Y，所以對它們執行 X 可能也有意義？”。說“我們不對檔案執行相同的 X，因為…​”將幫助他們決定推理是否合理（在這種情況下，他們不會浪費時間擴充套件你的程式碼以涵蓋檔案），或者以不同的方式推理（在這種情況下，他們可以解釋為什麼他們也擴充套件你的程式碼以涵蓋檔案）。

你的日誌訊息的目標是傳達你的更改背後的“為什麼”，以幫助未來的開發人員。審閱者還將確保你提議的日誌訊息很好地達到此目的。

提交訊息的第一行應該是一個簡短的描述（軟限制為50個字元，請參見 git-commit[1] 中的 DISCUSSION），並且不應以句號結尾。在大多數情況下，約定俗成地以“area: ”作為第一行的字首，其中 area 是被修改程式碼的通用區域的檔名或識別符號，例如：

  • doc: clarify distinction between sign-off and pgp-signing

  • githooks.txt: improve the intro section

如果對使用哪個識別符號有疑問，請在你修改的檔案上執行 git log --no-merges 以檢視當前約定。

“area:”字首後的標題句末尾省略句號，並且其第一個單詞不大寫（大寫省略僅適用於標題的“area:”字首之後的單詞），除非有其他理由需要大寫它，而不僅僅因為它是一個句子的第一個單詞。例如，“doc: clarify…​”而不是“doc: Clarify…​”，或者“githooks.txt: improve…​”而不是“githooks.txt: Improve…​”。但是“refs: HEAD is also treated as a ref”是正確的，因為即使 HEAD 出現在句中，我們也將其全大寫。

正文應提供有意義的提交訊息，其中：

  1. 解釋更改試圖解決的問題，即在沒有更改的情況下當前程式碼有什麼問題。

  2. 說明更改解決問題的方式是合理的，即為什麼更改後的結果更好。

  3. （如果存在）考慮過但已放棄的備選方案。

描述現狀的問題陳述應使用現在時態。寫“程式碼在給定輸入 Y 時執行 X”，而不是“程式碼在給定輸入 X 時曾執行 Y”。你不需要說“當前”——根據專案約定，問題陳述中的現狀指的是沒有你的更改的程式碼。

以祈使語氣描述你的更改，例如，“使 xyzzy 執行 frotz”而不是“[此補丁]使 xyzzy 執行 frotz”或“[我]更改了 xyzzy 以執行 frotz”，就好像你在命令程式碼庫改變其行為一樣。嘗試確保你的解釋無需外部資源即可理解。不要提供郵件列表存檔的 URL，而是總結討論的相關要點。

在歷史中“更穩定”的部分（即在 maint、master 和 next 等分支上）引用另一個提交有幾個原因：

  1. 引入你正在修復的 bug 根本原因的提交。

  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 尾行來認證你的工作

為了更好地追蹤誰做了什麼，我們要求你透過“簽署”（"signing off"）你的補丁來證明你編寫了該補丁，或者有權在與我們相同的許可下傳遞它。沒有簽署，我們無法接受你的補丁。

如果（且僅當）你認證以下 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: 用於註明發現補丁試圖修復的 bug 的人。

  2. Acked-by: 表示更熟悉補丁試圖修改區域的人喜歡該補丁。

  3. Reviewed-by:，與其他尾行不同，此行只能由審閱者在詳細分析後完全滿意補丁時提供。

  4. Tested-by: 用於表明此人應用了補丁並發現它達到了預期效果。

  5. Co-authored-by: 用於表明人們在提交補丁之前交換了草稿。

  6. Helped-by: 用於註明建議更改想法但未以補丁形式提供精確更改的人。

  7. Mentored-by: 用於註明在指導專案（例如 GSoC 或 Outreachy）中幫助開發補丁的人。

  8. Suggested-by: 用於註明建議補丁想法的人。

雖然如果情況允許，你也可以建立自己的尾行，但我們鼓勵你使用上面突出顯示的本專案中的常用尾行之一。

只將尾行的第一個字母大寫，即優先使用“Signed-off-by”而不是“Signed-Off-By”，以及“Acked-by:”而不是“Acked-By”。

使用 Git 工具從你的提交中生成補丁。

基於 Git 的差異工具生成 unidiff 格式，這是首選格式。

如果你的補丁涉及檔案重新命名，你無需害怕對 git diff 或 git format-patch 使用 -M 選項。接收方可以很好地處理它們。

請確保你的補丁沒有新增被註釋掉的除錯程式碼，或包含任何與你的補丁旨在實現的功能無關的額外檔案。生成補丁後務必進行審查，以確保準確性。在傳送之前，請確保它能幹淨地應用到你在“選擇一個起點”部分選擇的起點。

注意
 從審查你補丁的人的角度來看，master 分支是預設的預期起點。因此，如果你選擇了不同的起點，請在你的附函中說明這一選擇。

傳送你的補丁。

選擇你的審閱者

注意
 可能與安全相關的補丁應私下提交給 Git 安全郵件列表[1]，而不是公開郵件列表。

傳送補丁時，將“收件人”（To:）設定為郵件列表，並將“抄送”（cc:）列出與你正在修改的區域相關的人（contrib/contacts/[2] 中的 git-contacts 指令碼可以幫助識別他們），以徵求評論和審查。此外，當你將你的主題試合併到 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: 等尾行，以感謝幫助你補丁的人，並在傳送此類最終版本以供收錄時“抄送”他們。

format-patch 和 send-email

如果可能，學習使用 format-patch 和 send-email。這些命令已針對傳送補丁的工作流程進行了最佳化，避免了你現有的電子郵件客戶端（通常針對“multipart/*”MIME 型別電子郵件進行最佳化）可能導致你的補丁無法使用的許多方式。

注意
 這裡我們概述了使用 format-patch 和 send-email 的流程，但你也可以使用 GitGitGadget 傳送你的補丁（參見 MyFirstContribution）。

Git 郵件列表中的人需要能夠閱讀和評論你提交的更改。對於開發人員來說，能夠使用標準電子郵件工具“引用”你的更改以便他們可以評論你的程式碼的特定部分非常重要。因此，每個補丁都應該作為單獨訊息的“內聯”提交。

補丁系列的所有後續版本及其他相關補丁應歸入其各自的電子郵件執行緒，以幫助讀者找到系列的所有部分。為此，請將它們作為對附加“附函”訊息（見下文）、第一個補丁或相應的先前補丁的回覆傳送。這裡有一個分步指南，說明如何提交補丁系列的更新版本。

如果你的日誌訊息（包括 Signed-off-by 尾行中的姓名）無法用 ASCII 寫入，請確保你以正確的編碼傳送訊息。

警告
 警惕你的 MUA（郵件使用者代理）的自動換行功能破壞你的補丁。不要剪下貼上你的補丁；如果你不小心，可能會因此丟失製表符。

通常，在郵件主題行前加上 `[PATCH]` 是一個慣例。這使得人們可以輕鬆區分補丁和其他電子郵件討論。也鼓勵在方括號內除了 `PATCH` 之外使用其他標記來描述補丁的性質。例如，`[RFC PATCH]`（其中 RFC 代表“徵求意見”）通常用於表示補丁在被接受之前需要進一步討論，當你傳送之前已傳送內容的更新時，經常會看到 `[PATCH v2]`、`[PATCH v3]` 等。

git format-patch 命令遵循當前最佳實踐來格式化電子郵件正文。補丁的開頭應該是你的提交訊息，以 Signed-off-by 尾行結束，然後是一行由三個破折號組成，接著是 `diffstat` 資訊和補丁本身。如果你正在轉發別人的補丁，可以在電子郵件訊息開頭、提交訊息開始之前，選擇性地新增一個“From: ”行來註明該人的姓名。要將主題中預設的“[PATCH]”更改為“[]”，請使用 git format-patch --subject-prefix=<text>。作為快捷方式，你可以使用 --rfc 代替 --subject-prefix="RFC PATCH"，或者使用 -v <n> 代替 --subject-prefix="PATCH v<n>"。

除了提交訊息本身之外，你通常還希望新增關於補丁的額外解釋。將此類“附函”內容放在三個破折號線和 `diffstat` 之間。對於需要多次迭代審查和討論的補丁，每次迭代之間的更改說明可以儲存在 Git-notes 中，並透過 git format-patch --notes 自動插入到三破折號線之後。

這是實驗性的.

傳送主題時，你可以提出一個一段式摘要，該摘要在被選中時應出現在“正在進行中”（What's cooking）報告中，以解釋該主題。如果你選擇這樣做，請編寫一個2-5行的段落，使其能很好地融入我們的釋出說明（有關示例，請參閱 Documentation/RelNotes/* 檔案中的許多專案符號條目），並使其成為附函的第一段。對於單個補丁系列，請使用三破折號線和 `diffstat` 之間的空間，如前所述。

不要將補丁作為 MIME 附件附加，無論是否壓縮。不要讓你的電子郵件客戶端傳送 quoted-printable。不要讓你的電子郵件客戶端傳送 format=flowed，這會破壞你補丁中的空白字元。許多流行的電子郵件應用程式不總是將 MIME 附件作為純文字傳輸，這使得無法評論你的程式碼。MIME 附件也需要更多時間來處理。這並不會降低你的 MIME 附件更改被接受的可能性，但會使其更有可能被推遲。

例外：如果你的郵件程式正在損壞補丁，那麼有人可能會要求你使用 MIME 重新發送它們，這是可以的。

不要 PGP 簽名你的補丁。你的維護者或列表上的其他人很可能沒有你的 PGP 金鑰，無論如何也不會費心去獲取。你的補丁不是根據你是誰來判斷的；來自未知來源的優秀補丁比來自已知、受尊敬但做得不好或不正確的來源的補丁有更好的機會被接受。

如果你真的非常非常非常非常想進行 PGP 簽名的補丁，請將其格式化為“multipart/signed”，而不是以 -----BEGIN PGP SIGNED MESSAGE----- 開頭的純文字訊息。那不是純文字，而是其他東西。

處理衝突和迭代補丁

在修訂你的補丁所做的更改時，承認與其他正在進行的主題可能存在的衝突非常重要。為了有效處理這些潛在衝突，請遵循下面概述的建議步驟：

  1. 在一個合適的基礎分支上構建，參見上文，並對系列進行 `format-patch`。如果你正在原地執行“rebase -i”以從上一輪更新，這將重用以前的基礎，因此（2）和（3）可能會變得微不足道。

  2. 找到上一輪排隊的基礎

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

  3. 應用你的 `format-patch` 結果。有兩種情況：

    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/ 來自 `git-gui` 專案，由 Johannes Sixt 維護

    https://github.com/j6t/git-gui
    Contibutions should go via the git mailing list.

  • gitk-git/ 來自 `gitk` 專案，由 Johannes Sixt 維護

    https://github.com/j6t/gitk
    Contibutions should go via the git mailing list.

  • po/ 來自本地化協調員姜鑫

    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 上測試你的更改。有關最近 CI 執行的示例，請參見 https://github.com/git/git/actions/workflows/main.yml。

按照以下步驟進行初始設定：

  1. 將 https://github.com/git/git 派生（fork）到你的 GitHub 賬戶。你可以在這裡找到如何派生的詳細說明：https://help.github.com/articles/fork-a-repo/

初始設定完成後，每當你向你在 GitHub 上的 Git 派生倉庫推送新更改時，CI 將執行。你可以在這裡監控所有分支的測試狀態：https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml

如果一個分支未能透過所有測試用例，它將被標記為紅色 x，而不是綠色對勾。在這種情況下，你可以點選失敗的任務並導航到“ci/run-build-and-tests.sh”和/或“ci/print-test-failures.sh”。你還可以下載“Artifacts”（工件），它們是包含打包（或壓縮）的測試資料的 zip 歸檔檔案，這些資料與除錯相關。

然後修復問題並將你的修復推送到你的 GitHub 派生倉庫。這將觸發一次新的 CI 構建，以確保所有測試透過。

MUA 特定的提示

我收到或從列表中選取的某些補丁存在常見的破壞模式。請確保你的 MUA（郵件使用者代理）已正確設定，不會破壞空白字元。

有關透過將補丁郵寄給自己並使用 git-am[1] 應用來檢查補丁的提示，請參見 git-format-patch[1] 的 DISCUSSION 部分。

在進行此操作時，請檢查應用補丁的試執行所產生的提交日誌訊息。如果最終提交中的內容與你期望看到的完全不符，你的維護者很可能在應用你的補丁時手動編輯日誌訊息。像“Hi, this is my first patch.\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