Git
章節 ▾ 第二版

6.3 GitHub - 維護專案

維護專案

現在我們已經熟悉如何貢獻專案了，讓我們來看看另一方面：建立、維護和管理您自己的專案。

建立新的儲存庫

讓我們建立一個新的儲存庫來分享我們的專案程式碼。首先，按一下儀表板右側的「New repository」按鈕，或從頂部工具列中您的使用者名稱旁邊的 + 按鈕，如「New repository」下拉式選單所示。

The “Your repositories” area
圖 109. 「您的儲存庫」區域
The “New repository” dropdown
圖 110. 「New repository」下拉式選單

這會將您帶到「new repository」表單

The “new repository” form
圖 111. 「new repository」表單

您真正需要做的就是提供專案名稱；其餘欄位都是完全可選的。現在，只需按一下「Create Repository」按鈕，然後砰！您在 GitHub 上就有了一個名為 <user>/<project_name> 的新儲存庫。

由於您還沒有程式碼，GitHub 會顯示如何建立全新的 Git 儲存庫或連線現有 Git 專案的說明。我們在此不贅述；如果您需要複習，請查看Git 基礎。

現在您的專案已託管在 GitHub 上，您可以將 URL 提供給您想分享專案的任何人。GitHub 上的每個專案都可以透過 HTTPS 以 https://github.com/<user>/<project_name> 存取，並透過 SSH 以 git@github.com:<user>/<project_name> 存取。Git 可以從這些 URL 擷取和推送，但它們的存取權限會根據連線使用者的憑證進行控制。

注意

通常建議分享公開專案的 HTTPS URL，因為使用者不需要擁有 GitHub 帳戶即可存取它進行複製。如果使用者使用 SSH URL，則必須擁有帳戶並上傳 SSH 金鑰才能存取您的專案。HTTPS 的 URL 也與他們在瀏覽器中貼上以檢視專案的 URL 完全相同。

新增協作者

如果您與其他想要授予提交權限的人員一起工作，則需要將他們新增為「協作者」。如果 Ben、Jeff 和 Louise 都在 GitHub 上註冊了帳戶，並且您想授予他們推送權限，您可以將他們新增到您的專案。這樣做會授予他們「推送」權限，這表示他們對專案和 Git 儲存庫都具有讀取和寫入權限。

按一下右側邊欄底部的「Settings」連結。

The repository settings link
圖 112. 儲存庫設定連結

然後從左側選單中選取「Collaborators」。然後，只需在方塊中輸入使用者名稱，然後按一下「Add collaborator」。您可以重複此動作多次，以授予您想要的所有人員存取權限。如果您需要撤銷存取權限，只需按一下其列右側的「X」即可。

The repository collaborators box
圖 113. 儲存庫協作者方塊

管理提取請求

現在您有一個專案，其中包含一些程式碼，甚至可能有一些也具有推送權限的協作者，讓我們來看看當您收到提取請求時該怎麼辦。

提取請求可能來自您的儲存庫分支的分支，也可能來自同一個儲存庫中的另一個分支。唯一的區別在於，分支中的提取請求通常來自您無法推送至其分支且他們無法推送至您的分支的人員，而內部提取請求通常雙方都可以存取該分支。

在這些範例中，假設您是「tonychacon」，並且建立了一個名為「fade」的新 Arduino 程式碼專案。

電子郵件通知

當有人變更您的程式碼並向您發送 Pull Request 時，您應該會收到一封電子郵件通知，內容應該類似於新的 Pull Request 的電子郵件通知。

Email notification of a new Pull Request
圖 114. 新的 Pull Request 的電子郵件通知

關於這封電子郵件，有幾件事需要注意。它會提供一個小型的 diffstat，也就是 Pull Request 中已變更的檔案列表以及變更的幅度。它會提供一個 GitHub 上 Pull Request 的連結。它還會提供一些您可以從命令列使用的 URL。

如果您注意到 git pull <url> patch-1 這行，這是一種合併遠端分支的簡單方法，而無需新增遠端。我們在檢查遠端分支中快速介紹了這一點。如果您願意，您可以建立並切換到主題分支，然後執行此命令以合併 Pull Request 變更。

其他有趣的 URL 是 .diff 和 .patch URL，您可能猜到了，它們提供 Pull Request 的 unified diff 和 patch 版本。從技術上講，您可以使用類似這樣的方式合併 Pull Request 的工作

$ curl https://github.com/tonychacon/fade/pull/1.patch | git am

協作處理 Pull Request

正如我們在GitHub Flow中所涵蓋的那樣，您現在可以與開啟 Pull Request 的人進行對話。您可以使用 GitHub Flavored Markdown 在任何地方對特定的程式碼行、整個提交或整個 Pull Request 進行評論。

每次其他人對 Pull Request 發表評論時，您都會繼續收到電子郵件通知，以便您知道正在發生活動。它們各自都有一個指向發生活動的 Pull Request 的連結，您也可以直接回覆電子郵件來評論 Pull Request 的討論串。

Responses to emails are included in the thread
圖 115. 電子郵件的回覆會包含在討論串中

一旦程式碼達到您喜歡並想要合併的程度，您可以將程式碼拉下來並在本地合併，可以使用我們之前看到的 git pull <url> <branch> 語法，或者將 fork 新增為遠端並提取和合併。

如果合併很簡單，您也可以直接按下 GitHub 網站上的「合併」按鈕。這將執行「非快轉」合併，即使可以進行快轉合併，也會建立合併提交。這表示無論如何，每次您按下合併按鈕，都會建立一個合併提交。如您在合併按鈕以及手動合併 Pull Request 的說明中所見，如果您點擊提示連結，GitHub 會提供所有這些資訊。

Merge button and instructions for merging a Pull Request manually
圖 116. 合併按鈕以及手動合併 Pull Request 的說明

如果您決定不合併，您也可以直接關閉 Pull Request，開啟 Pull Request 的人將會收到通知。

Pull Request Refs

如果您正在處理大量的 Pull Request，並且不想每次都新增一堆遠端或執行一次性提取，GitHub 允許您執行一個巧妙的技巧。這是一個比較進階的技巧，我們將在Refspec中詳細介紹，但它可能相當有用。

GitHub 實際上會將儲存庫的 Pull Request 分支宣傳為伺服器上的偽分支。預設情況下，您在複製時不會取得它們，但它們以隱藏的方式存在，您可以輕鬆地存取它們。

為了說明這一點，我們將使用一個低階命令（通常稱為「水管」命令，我們將在水管和瓷器中閱讀更多關於它的資訊），稱為 ls-remote。此命令通常不用於日常 Git 操作，但它有助於顯示伺服器上存在哪些參考。

如果我們針對先前使用的「blink」儲存庫執行此命令，我們將取得儲存庫中所有分支、標籤和其他參考的列表。

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

當然，如果您在您的儲存庫中執行 git ls-remote origin 或您想要檢查的任何遠端，它會顯示類似於此的內容。

如果儲存庫在 GitHub 上，並且您有任何已開啟的 Pull Request，您將會取得這些以 refs/pull/ 為字首的參考。這些基本上是分支，但由於它們不在 refs/heads/ 下，因此您在從伺服器複製或提取時通常不會取得它們 — 提取的過程通常會忽略它們。

每個 Pull Request 有兩個參考 - 以 /head 結尾的參考指向與 Pull Request 分支中最後一次提交完全相同的提交。因此，如果有人在我們的儲存庫中開啟一個 Pull Request，並且他們的分支名稱為 bug-fix，而且它指向提交 a5a775，那麼在我們的儲存庫中，我們將不會有 bug-fix 分支（因為它在他們的 fork 中），但我們將會有 pull/<pr#>/head 指向 a5a775。這表示我們可以輕鬆地一次提取每個 Pull Request 分支，而無需新增一堆遠端。

現在，您可以執行類似於直接提取參考的操作。

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

這告訴 Git，「連線到 origin 遠端，並下載名為 refs/pull/958/head 的 ref。」Git 很樂意地服從，並下載建構該 ref 所需的一切，並在 .git/FETCH_HEAD 下放置一個指向您想要的提交的指標。您可以使用 git merge FETCH_HEAD 將其合併到您想要測試的分支中，但是該合併提交訊息看起來有點奇怪。此外，如果您正在審閱大量的 Pull Request，這會變得乏味。

還有一種方法可以提取所有的 Pull Request，並在您連線到遠端時保持它們的更新。在您最喜歡的編輯器中開啟 .git/config，並尋找 origin 遠端。它應該看起來有點像這樣

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

以 fetch = 開頭的那行是「refspec」。它是一種將遠端上的名稱與本地 .git 目錄中的名稱對應的方法。此特定的一行告訴 Git，「遠端上 refs/heads 下的東西應該進入我本地儲存庫的 refs/remotes/origin 下。」您可以修改此區段以新增另一個 refspec

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

最後一行告訴 Git，「所有看起來像 refs/pull/123/head 的 ref 都應該像 refs/remotes/origin/pr/123 一樣儲存在本地。」現在，如果您儲存該檔案，並執行 git fetch

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

現在，所有遠端 Pull Request 都以 ref 的形式在本地表示，這些 ref 的作用與追蹤分支非常相似；它們是唯讀的，並且會在您執行提取時更新。這使得在本地嘗試來自 Pull Request 的程式碼變得非常容易

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

眼尖的人會注意到 refspec 遠端部分的末尾有 head。GitHub 方面還有一個 refs/pull/#/merge ref，它表示如果您按下網站上的「合併」按鈕，將會產生的提交。這可以讓您在按下按鈕之前測試合併。

Pull Request 上的 Pull Request

您不僅可以開啟以主要或 master 分支為目標的 Pull Request，您實際上可以開啟以網路上任何分支為目標的 Pull Request。事實上，您甚至可以以另一個 Pull Request 為目標。

如果您看到一個 Pull Request 朝著正確的方向發展，並且您有一個關於它的變更想法，這個變更依賴於它，或者您不確定是否是個好主意，或者您沒有目標分支的推送權限，您可以直接對其開啟 Pull Request。

當您要開啟 Pull Request 時，頁面頂部有一個方塊，指定您要提取到哪個分支，以及您要從哪個分支提取。如果您點擊該方塊右側的「編輯」按鈕，您不僅可以變更分支，還可以變更哪個 fork。

Manually change the Pull Request target fork and branch
圖 117. 手動變更 Pull Request 的目標 fork 和分支

在這裡，您可以相當輕鬆地指定將您的新分支合併到另一個 Pull Request 或專案的另一個 fork 中。

提及和通知

GitHub 還內建了一個相當不錯的通知系統，當您有問題或需要來自特定個人或團隊的回饋時，它會派上用場。

在任何註解中，您可以開始輸入 @ 字元，它將開始自動完成專案中協作者或貢獻者的姓名和使用者名稱。

Start typing @ to mention someone
圖 118. 開始輸入 @ 以提及某人

您也可以提及不在該下拉式選單中的使用者，但自動完成程式通常可以加快速度。

一旦您發表包含使用者提及的註解，該使用者將會收到通知。這表示這可能是一種非常有效的方式，可以將人們拉入對話，而不是讓他們輪詢。在 GitHub 上的 Pull Request 中，人們通常會將團隊或公司中的其他人拉進來審閱 Issue 或 Pull Request。

如果有人在 Pull Request 或 Issue 中被提及，他們將會「訂閱」它，並且會在它發生任何活動時繼續收到通知。如果您開啟了某個項目、正在關注儲存庫或對某個項目發表評論，您也會訂閱該項目。如果您不再希望收到通知，則頁面上會有一個「取消訂閱」按鈕，您可以點擊它以停止接收關於它的更新。

Unsubscribe from an Issue or Pull Request
圖 119. 取消訂閱 Issue 或 Pull Request

通知頁面

當我們在這裡提到關於 GitHub 的「通知」時，我們指的是 GitHub 嘗試在事件發生時與您聯絡的特定方式，並且您可以透過幾種不同的方式設定它們。如果您從設定頁面進入「通知中心」標籤，您可以看到您擁有一些選項。

Notification center options
圖 120. 通知中心選項

您有兩種接收通知的方式：「電子郵件」和「網頁」。您可以選擇其中一種、兩種都選、或是都不選，來接收您主動參與的事項和您正在關注的儲存庫的活動通知。

網頁通知

網頁通知僅存在於 GitHub 上，您只能在 GitHub 上查看它們。如果您在偏好設定中選擇了這個選項，並且觸發了您的通知，您會在螢幕頂端的通知圖示上看到一個藍色小點，如通知中心所示。

Notification center
圖 121. 通知中心

如果您點擊該圖示，您將看到一份您收到通知的所有項目列表，並按專案分組。您可以點擊左側邊欄中的專案名稱來篩選特定專案的通知。您也可以點擊任何通知旁邊的勾選標記來確認通知，或者點擊群組頂部的勾選標記來確認專案中的所有通知。每個勾選標記旁邊還有一個靜音按鈕，您可以點擊該按鈕來不再接收該項目的任何通知。

所有這些工具對於處理大量通知都非常有用。許多 GitHub 進階使用者會直接關閉電子郵件通知，並透過這個畫面管理他們的所有通知。

電子郵件通知

電子郵件通知是您透過 GitHub 處理通知的另一種方式。如果您開啟此功能，您將收到每則通知的電子郵件。我們在以電子郵件通知發送的評論和新 Pull Request 的電子郵件通知中看到了這方面的例子。電子郵件也會正確地以線程方式顯示，如果您使用的是線程式電子郵件客戶端，這會很方便。

GitHub 發送給您的電子郵件的標頭中也嵌入了相當多的元數據，這對於設定自訂篩選器和規則非常有幫助。

例如，如果我們查看在新 Pull Request 的電子郵件通知中顯示的發送給 Tony 的實際電子郵件標頭，我們將在發送的資訊中看到以下內容

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

這裡有幾個有趣的地方。如果您想要強調或重新路由發送到此特定專案甚至是 Pull Request 的電子郵件，Message-ID 中的資訊會以 <使用者>/<專案>/<類型>/<ID> 格式提供所有資料。舉例來說，如果這是一個問題，<類型>欄位會是「issues」而不是「pull」。

List-Post 和 List-Unsubscribe 欄位表示，如果您有理解這些欄位的郵件客戶端，您可以輕鬆地發布到列表或「取消訂閱」此線程。這基本上與點擊網頁版通知上的「靜音」按鈕或在 Issue 或 Pull Request 頁面上的「取消訂閱」按鈕相同。

同樣值得注意的是，如果您同時啟用了電子郵件和網頁通知，並且您閱讀了電子郵件版本的通知，如果您的郵件客戶端允許顯示圖片，則網頁版本也會被標記為已讀。

特殊檔案

如果您的儲存庫中存在一些特殊檔案，GitHub 會注意到它們。

README

第一個是 README 檔案，它可以是 GitHub 識別為散文的幾乎任何格式。例如，它可以是 README、README.md、README.asciidoc 等。如果 GitHub 在您的原始碼中看到 README 檔案，它會在專案的首頁上渲染它。

許多團隊使用這個檔案來保存對於可能不熟悉儲存庫或專案的人來說的所有相關專案資訊。這通常包括以下內容：

  • 專案的用途

  • 如何配置和安裝它

  • 如何使用它或讓它運行的範例

  • 專案提供的授權

  • 如何為專案做出貢獻

由於 GitHub 會渲染這個檔案，您可以在其中嵌入圖片或連結，以方便理解。

CONTRIBUTING

GitHub 識別的另一個特殊檔案是 CONTRIBUTING 檔案。如果您有一個名為 CONTRIBUTING 的檔案，並帶有任何副檔名，當任何人開始開啟 Pull Request 時，GitHub 會顯示當存在 CONTRIBUTING 檔案時開啟 Pull Request。

Opening a Pull Request when a CONTRIBUTING file exists
圖 122. 當存在 CONTRIBUTING 檔案時開啟 Pull Request

這裡的想法是您可以指定您希望或不希望在發送到您的專案的 Pull Request 中包含的特定內容。這樣，人們可能會在開啟 Pull Request 之前實際閱讀指南。

專案管理

通常，您無法對單一專案執行許多管理操作，但有幾個項目您可能會感興趣。

變更預設分支

如果您正在使用「master」以外的分支作為您的預設分支，並且您希望人們開啟針對該分支的 Pull Request 或預設查看該分支，您可以在儲存庫的設定頁面上的「選項」標籤下變更它。

Change the default branch for a project
圖 123. 變更專案的預設分支

只需在下拉選單中變更預設分支，它將成為之後所有主要操作的預設，包括當有人複製儲存庫時預設簽出的分支。

轉移專案

如果您想將專案轉移給 GitHub 中的另一個使用者或組織，在儲存庫設定頁面的同一個「選項」標籤底部有一個「轉移所有權」選項，您可以使用它來執行此操作。

Transfer a project to another GitHub user or Organization
圖 124. 將專案轉移給另一個 GitHub 使用者或組織

如果您要放棄專案並且有人想要接管它，或者如果您的專案越來越大並且想要將其移動到組織中，這會很有幫助。

這不僅會將儲存庫及其所有關注者和星標移動到另一個位置，還會設定從您的 URL 到新位置的重新導向。它還會重新導向來自 Git 的複製和提取，而不僅僅是網頁請求。

scroll-to-top