章節 ▾ 第二版

6.3 GitHub - 維護專案

維護專案

現在我們已經熟悉了為專案做貢獻，讓我們來從另一個角度看看：建立、維護和管理自己的專案。

建立新倉庫

讓我們建立一個新的倉庫來分享我們的專案程式碼。首先，點選儀表盤右側的“新建倉庫”按鈕，或者點選頂部工具欄使用者名稱旁邊的 + 按鈕，正如 “新建倉庫”下拉選單 中所示。

The “Your repositories” area
圖 109. “我的倉庫”區域
The “New repository” dropdown
圖 110. “新建倉庫”下拉選單

這將帶您進入“新建倉庫”表單

The “new repository” form
圖 111. “新建倉庫”表單

您在這裡只需要提供一個專案名稱；其餘欄位完全是可選的。現在，只需點選“建立倉庫”按鈕，就完成啦——您在 GitHub 上有了一個新倉庫，名為 <user>/<project_name>。

由於您還沒有程式碼，GitHub 會顯示如何建立全新的 Git 倉庫或連線現有 Git 專案的說明。我們在此不多贅述；如果您需要回顧，請檢視 Git 基礎。

現在您的專案託管在 GitHub 上，您可以將 URL 提供給任何您想與之分享專案的人。GitHub 上的每個專案都可以透過 HTTPS 訪問，URL 為 https://github.com/<user>/<project_name>，或者透過 SSH 訪問，URL 為 git@github.com:<user>/<project_name>。Git 可以從這兩個 URL 獲取和推送，但它們都受連線使用者的憑據控制。

注意

對於公開專案，分享基於 HTTPS 的 URL 通常更可取，因為使用者在克隆時不需要 GitHub 賬戶即可訪問。如果提供 SSH URL，使用者將需要一個賬戶並上傳 SSH 金鑰才能訪問您的專案。HTTPS URL 也與使用者在瀏覽器中檢視專案時貼上的 URL 完全相同。

新增協作者

如果您正在與其他希望獲得提交許可權的人合作，您需要將他們新增為“協作者”。如果 Ben、Jeff 和 Louise 都註冊了 GitHub 賬戶，並且您想給他們推送到您的倉庫的許可權，您可以將他們新增到您的專案。這樣做會賦予他們“推送”許可權，這意味著他們對專案和 Git 倉庫擁有讀寫許可權。

點選右側邊欄底部的“設定”連結。

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

然後從左側選單選擇“協作者”。接著，只需在框中輸入使用者名稱，然後點選“新增協作者”。您可以根據需要重複此操作，為您喜歡的任何人授予訪問許可權。如果您需要撤銷訪問許可權，只需點選他們行右側的“X”。

The repository collaborators box
圖 113. 倉庫協作者框

管理拉取請求

現在您有了一個包含一些程式碼，甚至可能還有一些擁有推送許可權的協作者的專案，讓我們來看看當您收到拉取請求時該怎麼做。

拉取請求可能來自您倉庫的 fork 中的分支，也可能來自同一倉庫中的另一個分支。唯一的區別是，來自 fork 的拉取請求通常來自您無法推送到其分支的人，而他們也無法推送到您的分支；而對於內部拉取請求，雙方通常都可以訪問分支。

在這些示例中，我們假設您是“tonychacon”，並且您建立了一個名為“fade”的新的 Arduino 程式碼專案。

電子郵件通知

有人修改了您的程式碼並向您傳送了一個拉取請求。您應該會收到一封通知您新拉取請求的電子郵件，它看起來會像 新拉取請求的電子郵件通知。

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

關於這封郵件有幾點需要注意。它會給您一個小的 diffstat——一個已更改檔案列表以及更改的多少。它提供了一個指向 GitHub 上拉取請求的連結。它還提供了一些可以從命令列使用的 URL。

如果您注意到“git pull <url> patch-1”這一行，這是在不新增遠端倉庫的情況下合併遠端分支的一種簡單方法。我們在 檢出遠端分支 中快速回顧過這一點。如果您願意，可以建立一個主題分支並切換到該分支，然後執行此命令來合併拉取請求的更改。

其他有趣的 URL 是 .diff 和 .patch URL，正如您可能猜到的，它們提供統一的 diff 和 patch 格式的拉取請求。您實際上可以像這樣合併拉取請求的工作：

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

協作處理拉取請求

正如我們在 GitHub Flow 中所講，您現在可以與開啟拉取請求的人進行對話。您可以使用 GitHub Flavored Markdown 在任何地方評論特定的程式碼行、整個提交或整個拉取請求本身。

每次其他人評論拉取請求時，您都會繼續收到電子郵件通知，以便您瞭解正在發生的活動。每封郵件都會有一個指向發生活動的拉取請求的連結，您也可以直接回覆電子郵件來評論拉取請求執行緒。

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

一旦程式碼到了您喜歡並且想要合併它的地方，您就可以將程式碼拉下來並在本地合併，可以使用我們之前看到的 git pull <url> <branch> 語法，或者將 fork 新增為遠端倉庫並進行獲取和合並。

如果合併很簡單，您也可以直接點選 GitHub 網站上的“合併”按鈕。這將執行“非快進”合併，即使可以進行快進合併也會建立合併提交。這意味著，無論如何，每次點選合併按鈕時，都會建立一個合併提交。正如您在 合併按鈕和手動合併拉取請求的說明 中看到的，如果您點選提示連結，GitHub 會為您提供所有這些資訊。

Merge button and instructions for merging a Pull Request manually
圖 116. 合併按鈕和手動合併拉取請求的說明

如果您決定不想合併它，也可以直接關閉拉取請求，開啟它的人將會收到通知。

拉取請求引用

如果您處理的拉取請求**非常多**，並且不想每次都新增大量遠端倉庫或進行一次性拉取，GitHub 提供了一個巧妙的技巧。這有點高階，我們將在 Refspec 中更詳細地介紹，但它可能非常有用。

GitHub 實際上將倉庫的拉取請求分支作為伺服器上的偽分支進行宣傳。預設情況下，您在克隆時不會獲取它們，但它們以一種隱藏的方式存在，並且您可以很容易地訪問它們。

為了演示這一點，我們將使用一個低階命令（通常稱為“plumbing”命令，我們將在 Plumbing and Porcelain 中瞭解更多）稱為 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 上並且您有任何已開啟的拉取請求，您將獲得以 refs/pull/ 為字首的這些引用。這些基本上是分支，但由於它們不在 refs/heads/ 下，所以您在正常克隆或從伺服器獲取時不會得到它們——獲取過程通常會忽略它們。

每個拉取請求有兩個引用——以 /head 結尾的引用指向與拉取請求分支的最後一個提交完全相同的提交。因此，如果有人在我們的倉庫中打開了一個拉取請求，並且他們的分支名為 bug-fix，並且指向提交 a5a775，那麼在**我們**的倉庫中，我們不會有一個 bug-fix 分支（因為它在他們的 fork 中），但我們**會**有一個 pull/<pr#>/head 指向 a5a775。這意味著我們可以一次性輕鬆地拉取所有拉取請求分支，而無需新增大量遠端倉庫。

現在，您可以直接獲取該引用。

$ 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 的引用。” Git 會愉快地執行，下載構建該引用所需的所有內容，並將一個指向您想要的提交的指標放在 .git/FETCH_HEAD 下。您可以接著使用 git merge FETCH_HEAD 將其合併到您想測試它的分支中，但那個合併提交的訊息看起來有點奇怪。此外，如果您正在審查**大量**拉取請求，這會很繁瑣。

還有一種方法可以獲取**所有**拉取請求，並在您連線到遠端倉庫時保持它們的更新。用您喜歡的編輯器開啟 .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 的引用都應該本地儲存為 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
# …

現在所有遠端的拉取請求都在本地以類似跟蹤分支的方式表示；它們是隻讀的，並且在您執行 fetch 時會更新。這使得在本地嘗試拉取請求中的程式碼非常容易。

$ 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 引用，它代表如果您在網站上點選“合併”按鈕所產生的提交。這允許您在點選按鈕之前測試合併。

拉取請求的拉取請求

您不僅可以開啟針對主分支或 master 分支的拉取請求，實際上還可以開啟針對網路中任何分支的拉取請求。事實上，您甚至可以針對另一個拉取請求。

如果您看到一個拉取請求朝著正確的方向發展，並且您有一個基於它的更改想法，或者您不確定這個想法是否好，或者您只是沒有目標分支的推送許可權，您可以直接向它開啟一個拉取請求。

當您開啟拉取請求時，頁面頂部有一個框，指定您要拉取到哪個分支以及從哪個分支拉取。如果您點選該框右側的“編輯”按鈕，您不僅可以更改分支，還可以更改 fork。

Manually change the Pull Request target fork and branch
圖 117. 手動更改拉取請求的目標 fork 和分支

在這裡，您可以非常輕鬆地指定將您的新分支合併到另一個拉取請求或專案的另一個 fork 中。

提及和通知

GitHub 還內建了一個相當不錯的通知系統，當您有疑問或需要特定個人或團隊的反饋時，它會很有用。

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

Start typing @ to mention someone
圖 118. 輸入 @ 來提及某人

您也可以提及下拉列表中沒有的使用者，但自動補全通常可以加快速度。

一旦您釋出包含使用者提及的評論，該使用者就會收到通知。這意味著這是一種將人們引入對話的有效方式，而不是讓他們輪詢。在 GitHub 的拉取請求中，人們經常會拉入他們團隊中或公司中的其他人來審查問題或拉取請求。

如果某人在拉取請求或問題中被提及，他們將被“訂閱”該項，並在發生任何活動時繼續收到通知。如果您打開了某項，或者您正在關注某個倉庫，或者您評論了某項，您也會被訂閱。如果您不再希望收到通知，頁面上有一個“取消訂閱”按鈕，您可以點選它來停止接收更新。

Unsubscribe from an Issue or Pull Request
圖 119. 取消訂閱某個問題或拉取請求

通知頁面

當我們在 GitHub 中提到“通知”時，我們指的是 GitHub 在事件發生時與您聯絡的一種特定方式，並且有幾種不同的配置方式。如果您從設定頁面轉到“通知中心”選項卡，您可以看到一些可用的選項。

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

您可以選擇透過“電子郵件”和“Web”接收通知，對於您積極參與的事項和您正在關注的倉庫的活動，您可以選擇其中一項、都不選或兩者都選。

Web 通知

Web 通知僅存在於 GitHub 上，並且您只能在 GitHub 上檢視它們。如果您在首選項中選擇了此選項，並且觸發了通知，您將在螢幕頂部的通知圖示上看到一個小的藍色圓點，如 通知中心 所示。

Notification center
圖 121. 通知中心

如果您點選它，您將看到一個列表，其中包含您被通知到的所有專案，按專案分組。您可以透過單擊左側邊欄中的專案名稱來過濾特定專案的通知。您還可以透過單擊任何通知旁邊的複選標記圖示來確認通知，或者透過單擊組頂部的複選標記來確認一個專案中的**所有**通知。每個複選標記旁邊還有一個靜音按鈕，您可以點選它來停止接收該專案的進一步通知。

所有這些工具對於處理大量通知都非常有用。許多 GitHub 高階使用者會完全關閉電子郵件通知，並透過此螢幕管理所有通知。

電子郵件通知

電子郵件通知是您可以透過 GitHub 處理通知的另一種方式。如果您開啟此選項，您將收到每條通知的電子郵件。我們在 作為電子郵件通知傳送的評論 和 新拉取請求的電子郵件通知 中看到了這方面的示例。電子郵件也會被正確地進行執行緒化，如果您使用支援執行緒的電子郵件客戶端，這會很好。

GitHub 傳送的電子郵件頭部還嵌入了相當多的元資料，這對於設定自定義過濾器和規則非常有幫助。

例如，如果我們檢視在 新拉取請求的電子郵件通知 中顯示的電子郵件傳送給 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

這裡有幾件有趣的事情。如果您想突出顯示或將電子郵件重新路由到此特定專案甚至拉取請求，Message-ID 中的資訊以 <user>/<project>/<type>/<id> 格式提供了所有資料。例如，如果這是一個問題，<type> 欄位將是“issues”而不是“pull”。

List-Post 和 List-Unsubscribe 欄位意味著，如果您有一個理解這些欄位的郵件客戶端，您可以輕鬆地釋出到列表或“取消訂閱”執行緒。這基本上與點選 Web 版本通知上的“靜音”按鈕或在問題或拉取請求頁面本身上點選“取消訂閱”相同。

還值得注意的是，如果您同時啟用了電子郵件和 Web 通知，並且您閱讀了通知的電子郵件版本，那麼如果您在郵件客戶端中允許顯示影像，Web 版本也會被標記為已讀。

特殊檔案

GitHub 會注意到您倉庫中的幾個特殊檔案。

README

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

許多團隊使用此檔案來存放所有相關的專案資訊，供可能剛接觸該倉庫或專案的新人查閱。這通常包括以下內容：

  • 專案的作用

  • 如何配置和安裝它

  • 如何使用它或使其執行的示例

  • 專案提供的許可證

  • 如何為其做出貢獻

由於 GitHub 會渲染此檔案，您可以在其中嵌入影像或連結以方便理解。

CONTRIBUTING

GitHub 識別的另一個特殊檔案是 CONTRIBUTING 檔案。如果您有一個名為 CONTRIBUTING 的檔案（無論副檔名如何），當任何人開始開啟拉取請求時，GitHub 將會顯示 存在 CONTRIBUTING 檔案時開啟拉取請求。

Opening a Pull Request when a CONTRIBUTING file exists
圖 122. 存在 CONTRIBUTING 檔案時開啟拉取請求

這樣做的目的是您可以指定您希望或不希望在傳送到您專案的拉取請求中出現的內容。這樣，人們在開啟拉取請求之前可能會實際閱讀指南。

專案管理

通常，您對單個專案可以進行的管理操作不多，但有幾項可能值得關注。

更改預設分支

如果您使用的是“master”以外的分支作為預設分支，並且希望人們在其上開啟拉取請求或預設檢視該分支，您可以在倉庫設定頁面的“選項”選項卡下更改它。

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

只需在下拉列表中更改預設分支，它將成為之後所有主要操作的預設分支，包括當有人克隆倉庫時預設檢出的分支。

轉移專案

如果您想將專案轉移到 GitHub 上的另一個使用者或組織，您的倉庫設定頁面的“選項”選項卡底部有一個“轉移所有權”選項，允許您執行此操作。

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

這對於您放棄專案並有人想接管，或者您的專案變得越來越大並想將其移入組織時很有幫助。

這不僅會連同所有關注者和 Star 一起將倉庫移動到其他地方，還會從您的 URL 設定一個重定向到新的位置。它還將重定向 Git 的克隆和獲取請求，而不僅僅是 Web 請求。