如何 Git(hub)

如果你想協助建立 Sponge，你有一個很棒的 API 添加，或者你想改善我們的文件，那麼你需要熟悉 git 和 GitHub。如果您已經熟悉 Fork、分支（Branch）、問題（Issue）、拉取請求（Pull Request）和提交（commit），那麼就跳過這個話題。 如果你不知道我們在說些什麼，那麼你繼續讀吧。

備註

此指南假設您已經閱讀 安裝 Git，並且您已經使用您選擇的 Git 客戶端設定了您的電腦。

Git 和 GitHub 的基本概念

Git 允許許多不同的開發人員同時開發一個軟體。GitHub 是一個開發人員可以與其他人協作和共享工作的網站。GitHub 依靠 Git 來管理上述工作。

小訣竅

如果您不熟悉 Git 與 GitHub 詞彙，請參考 GitHub 上的詞彙頁面。

Repo Overview

在這種情況下，儲存庫（Repo）被命名為``SpongePowered``，有兩個分支名為``master`` 和 feature 1，並且在兩個分支都有一些提交。

讓我們把這些術語放到上下文意中——從 repository 開始。儲存庫（repository，簡稱：repo）是專案儲存檔案的地方。SpongePowered 儲存庫位於 GitHub。然而，這個儲存庫有一些訪問限制，以防止非預期或惡意的修改。您不能直接自行修改，因為儲存庫對一般用戶是唯讀的。現在您可能想知道您該如何提交建議和修改。而這就是 fork 的作用。您可以抓取 SpongePowered 儲存庫的副本，並在那裡進行修改。完成後，在儲存庫中將其開啟為 Pull Tequest（PR）。工作人員會審查您提出的添加和更改，告訴你是否有問題或需要改進，並合併最後的 PR。

在詳細討論之前，以下是上述程序的簡短摘要：

  1. Fork 你所選擇的儲存庫

  2. 克隆（Clone）到您的電腦上

  3. 建立一個新的分支

  4. 作出所需的更改

  5. 測試一切能運作

  6. 提交更改

  7. 將它們同步到 GitHub

  8. 將這些更改向 SpongePowered 儲存庫提出 PR

  9. 必要時修改您的 PR

  10. 你的 PR 被員工合併進 master

請詳細說明！

1. Fork 儲存庫

備註

只有在您對更改的儲存庫沒有推送權限的情況下，才需要執行此步驟。 如果你正在自己的儲存庫工作，是沒有必要 fork 的。只需跳過這一步，並直接 clone 即可。如果您對 Sponge 進行了更改，並且您不是員工，則需要執行此步驟。

現在你知道了基本概念，我們將討論細節。首先，需要 fork 要更改的儲存庫。這可以在 GitHub.com 上完成，在儲存庫頁面的頂部找到 Fork 按鈕。按下後，GitHub 會做一些工作，並向您提供原始儲存庫的克隆。您會注意到該克隆現在位於 你的 GitHub 帳號/克隆的儲存庫名稱。好了，第一步完成。

備註

原始儲存庫中的所有分支也將 fork，您會收到與被 fork 的儲存庫一模一樣克隆。

Repo forking

2. 把 fork 克隆到您的電腦

現在你需要把這個 fork 拿到你的電腦上來進行更改。打開你選擇的 Git 客戶端（安裝 Git）並 clone 你的 fork 到你的電腦。 客戶端會要求您提供一個資料夾來儲存所有內容。第二步完成，做得好！

備註

大多數步驟可以通過您選擇的 GUI 完成。如果你使用指令界面的經驗，也可以使用它。每個步驟都會展示所需的命令，以達到期望的結果。

另外，你可以通過 CLI（command line interface，指令介面，Windows 下的 CMD 或 powershell）來完成這個任務。請注意，在輸入此指令之前，您需要建立將克隆所有東西的資料夾：

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
Repo cloning

3. 建立一個新的分支

現在你有了一個你的 fork 的本地克隆，是時候建立一個分支來工作。分支被設計成能夠同時開發和測試不同的功能或添加，而不會因添加的干擾而引起問題和錯誤。強烈建議你不要在 master 分支上進行修改。取而代之，自己建立一個新的分支（用一個具有意義的名稱），並在那裡做更改。

這意味著我們需要先創建一個 分支 ``\ ，所以我們開始吧！你可以通過客戶端（在某處應該有一個 ``建立分支 按鈕），也可以透過 CLI 用 git 來完成：

git checkout -b [name_of_your_new_branch]

這將使用你選擇的名稱建立一個 分支，並切換到此。你即將做出的所有更改都將會在此分支上。如果您需要切換到另一個分支（例如 master），只需重新使用此指令。第三步完成！到目前為止都很好！要得到你的分支的概貌，只需看看你的 git 客戶端或使用：

git branch
Branches

是時候進行更改了。請使用您選擇的編輯器或 IDE 來執行此操作。

4. 測試您的更改是否能運作

你必須對 SpongeAPI 及其實作執行 gradle compileJava 。如果能在沒有錯誤的情況下完成，請繼續下一步。如果發生錯誤，請作出適當的更正並重試。

對於 SpongeDocs 而言，你只需要提交您的 PR，它會自動建置並顯示可能出現的錯誤。另一種選擇是於本機建置 Docs。查看 Docs上的 Readme.md 以獲取更多說明。

5. 提交更改

完成後，需要將它們打包起來（也就是一個 commit ）中，並將它們放入分支中。你的 git 客戶端將再次將幫助你。請為您的提交添加一個有意義的名稱，如果需要，添加一個簡短描述。這也可以通過 CLI 完成：

首先收集你想要提交的所有檔案和資料夾：

git add <file>
git add <folder>

現在，檔案被添加到您想要包含在提交中的更改列表中，這樣做即可

git commit

它會打開一個文本視窗，如果你想要，在那裡你可以添加一個消息。 看看下面的圖片。你會注意到你的提交仍然儲存在本地，而不是在 GitHub 的 fork 上。

備註

您可以在一個 PR 中進行多個提交。馬上進行吧，更改你所需的一切，並把更改提交。稍後您可以將多提交合併到單個提交之中。

所以現在，第六步就完成了。幾乎要完成了！

Committing

6. 同步到 GitHub

現在我們需要將這些變更套用到 GitHub 上你的 fork。到目前為止，您所做的一切只被儲存於本機。與往常一樣，你可以使用你的 git 客戶端來做到這一點（你的GUI某處有一個按鈕），或者你可以通過 CLI 來完成：

git push <remote> <branch>

在這種情況下，應該是這樣：

git push origin feature/YourFeature
Pushing commits

7. 向 SpongePowered 儲存庫將更改提交 PR

你可以去 GitHub.com 上的 Forks 頁面（應該在你的 Forks 頁面的頂部有一個通知來指導你），或者你可以使用你的 GitHub 客戶端來建立一個 Pull Request。Windows 的 GitHub 官方客戶端的將其放在視窗的右上角。

PRs

8. 如有必要，修改您的 PR

如果我們想要對你的 PR 進行更改，那麼只需要對上面建立的分支進行更多的提交。新的提交將自動添加到您的 PR 中。

9. 你的 PR 被 Pull 了

就是如此。我們都準備好了！做得很好！

進階的 Git

折疊提交（Squash）與變基（Rebase）

假設你已經完成了對儲存庫的補充，假設你完成了137次提交。 你的提交歷史肯定會顯得非常混亂。如果它們都被記錄在資料庫中，這將會非常難堪，不是嗎？太多零碎的提交也會混淆專案的提交歷史。很幸運地，Git 有一個很好的工具來迴避這麻煩，它叫做``rebase``。 Rebase 可以把你的137項小提交合併成一個大提交。很讚對吧？而不是重新發明輪子，我們會傳給你一個簡短、容易理解的折疊提交（squash）教學連結：

Gitready: Squashing with Rebase

這就是它所做的，很好的視覺化展示：

Squashing commits

設定遠端

自然的，原始儲存庫是您的 Fork 的直接 parent，您的 Fork 是本地克隆的直接 parent。然而，原始的儲存庫不是您的克隆的直接 parent。這不是首要問題，但它阻止您將克隆更新到原始儲存庫的最新更改。如果您將原始儲存庫設定為您的克隆的遠端（讀取：「parent」），您將能夠獲取對此儲存庫所做的所有更改，並將其應用到您的本地克隆。看下面看看如何抓取和更新工作。

Setting up a remote

好了。這一步是通過 CLI 完成的，因為大多數 GUI 都缺少這個（相當先進的）功能：

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

如果您不確定該功能是否如預期運作，或者您想檢查目前設定了哪些遠端，則可以透過以下方式進行檢查：

git remote -v

輸出應該像這樣：

origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

備註

如果看到警告 fatal: The current branch 你的分支名稱 has no upstream branch.，那麼分支可能不在 upstream 遠端。如果這是您第一次推送新分支的提交，則可能會發生這種情況。要推送當前分支並將遠端設置為 upstream，請使用 git push --set-upstream origin 你的分支名稱。

變基（Rebasing）

假設你對你想要的分支做了一些更改，但同時有人更新了儲存庫。這意味著你的 fork 和你的克隆是過時的。這不是一個大問題，但為了避免以後合併您的添加時出現問題，強烈建議您將您的變更 rebase 到原始儲存庫的最新更改進行。如果您還沒有設定遠端儲存庫，請在嘗試變基（rebase）之前進行。

一個成功的 rebase 需要幾個步驟：

1. 獲取（Fetch）遠端儲存庫的更改

首先，您需要抓取遠端儲存庫上的更改。請（再次）透過 CLI 執行：

git fetch upstream

這將添加來自遠端 upstream 的所有更改，並將其放入臨時的 upstream/master 分支。

2. 本地合併遠端更改

現在我們需要選擇我們的本地 master 分支：

git checkout master

之後，我們將包含在 upstream/master 中的更改合併到本地的 master 分支中：

git merge upstream/master

好了，這就是我們到此為止所做的：

Rebasing 1

3. 將本地分支變基到已更新的主線

接下來是將您正在將工作中的本地分支 rebase 到 master。我們需要切換到你的工作分支（這裡：feature/你的功能），然後執行 rebase。這操作是通過：

git checkout feature/yourfeature
git rebase master

這將倒回你的分支，然後在 master 分支再次套用您自己的更改。結果如下所示：

Rebasing 2

4. 把一切推送到你的 fork

我們需要做的最後一件事是把所有東西都推到 fork 上。如果您已經創建了一個 PR，它會自動被更新：

git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Rebasing 3

你做到了，真棒！做得好，感謝與 Rebase-Air 同飛！