Pro Git

很多人作版本控制的方法是把檔案複製到另一個目錄（如果他們夠聰明的話，他們還會幫資料夾加上時間）。 這種做法很常見，因為這樣做很簡單，但是卻也非常容易產生離譜的錯誤。 這種做法非常容易搞混資料夾，意外寫錯檔案或複製覆蓋到不想要的檔案。

為了解決這個問題，程式設計師很久以前就開發了很多種本機版本控制系統，大多都是採用某種簡單的資料庫來紀錄檔案的所有變更記錄。

其中最流行的一種叫做 RCS，至今許多電腦上都還可以找到他的蹤影。 甚至在流行的 Mac OS X 系統中，只要安裝了開發者工具包以後，你就會有 rcs 的指令可以使用。 RCS 的工作原理是在硬碟上保存一堆特殊格式的補丁集合（patch set，即檔案從一個版本變更到另一個版本所需資訊）；通過套用任意的補丁，便可以重新產生出每個版本的檔案內容。

接下來人們又遇到了重大問題，就是如何和其他電腦上的開發者協同合作？ 為了解決這個問題，於是集中化的版本控制系統應運而生。 這類系統（如：CVS、Subversion 和 Perforce），都有一個伺服器來管理所有版本的檔案，而許多用戶端會連到這台伺服器取出檔案來使用。 多年以來，這儼然成為版本控制系統的標準做法。

相對於本機版本控制系統，這種做法帶來了許多好處。 舉例來說，每個人都可以一定程度的知道專案中的其他人正在做些什麼。 管理員也可以輕鬆掌控每個開發者的權限；而且比每個用戶端只用本機的版本控制系統好管理很多。

然而，集中化的版本控制系統也有一些嚴重的缺點。 最嚴重的當然是中央伺服器如果發生故障的時候。 如果當機一小時，那麼這個小時之中，沒有人可以提交更新，也就無法協同合作。 如果中心版本庫的硬碟發生損壞，又沒有做適當的備份，那麼你就絕對會遺失所有資料——包括專案的全部變更歷史，只會剩下用戶端各自機器上保留的單獨快照。 本機版本控制系統也存在類似的問題——只要你的專案歷史都放在同一個地方，就有遺失所有資料的風險。

於是分散式版本控制系統（Distributed Version Control Systems，簡稱 DVCSs）就此登上舞台。 在 DVCS 系統（如 Git、Mercurial、Bazaar 和 Darcs）中，用戶端並不只取出最新的檔案快照；還把整個倉儲做個鏡像。 假設有任何一個協同合作的伺服器故障，事後都可以用任何一個用戶端的鏡像來還原。 因為每個地方都有完整的資料備份。

除此之外，許多這類的系統都可以很好的和許多遠端倉儲互動，所以你可以和不同群組的人使用不同的方式，在同一個專案內協同合作。 你可以根據需要設定許多工作流程（如：階層式模型），這是在集中式的版本控制系統中是無法實現的。

Git 與其它版本控制系統（包含 Subversion 以及與它相關的）最主要的差別是如何處理資料的方式。 一般來說，其他大部分的系統是紀錄一連串檔案更改的資訊。 這些系統（CVS、Subversion、Perforce、Bazaar…等等）儲存一組基本的檔案以及這些檔案隨時間遞增的更動資料。

但是 Git 不是用這種方式儲存及看待這些資料， 而是將其視為小型檔案系統的一組快照（Snapshot）。 每當你提交（commit）（註：在 Git 儲存目前專案的狀態）時，Git 會紀錄下你所有目前檔案的樣子，並且參照到這次快照中。 為了講求效率，只要檔案沒有變更，Git 不會再度儲存該檔案，而是直接將上一次相同的檔案參照到這次快照中。 Git 把它的資料視為一連串的快照。

這是 Git 和其他相似的版本管理系統之間一個重要的差異。 它使得 Git 從各方面重新考量被其他老一輩版本管理系統所採用的作法， 並使得 Git 更像是一個上面有一些強大工具的小型檔案系統，而不僅只是版本管理系統。 本書將會在 使用 Git 分支 裡面介紹 Git 分支時，帶領你探索採用這種做法所獲得的好處。

大部份 Git 的操作皆只需要本地端的檔案及資源即可完成 — 通常並不需要網路上其它電腦的資訊。 如果你以前使用過每項操作都需要網路延遲的集中式版本控制系統，在這方面 Git 將會讓你覺得速度快到有如神助。 因為專案所有的歷史資料都存在你的本機磁碟中，大多數的操作看起來都像是瞬間完成的。

例如：想要瀏覽專案的歷史時，Git 不需要到伺服器下載歷史再顯示 — 就只需要從本機的資料庫讀取。 這意味著你幾乎馬上就可以看到專案的歷史。 若讀者想瞭解某個檔案一個月前的版本與現在版本的差別，Git 可以找出一個月前的檔案並在本機比對差異，而不是要求遠端的伺服器執行這項工作，或者從伺服器取回舊版本的檔案之後才在本機比對。

這也代表你只有一點點操作沒辦法在你斷線或是中斷 VPN 後執行。 如果你在飛機或火車上想要做些小工作，你可以愉快的提交並且等到連上網路後再上傳。 如果你回家後沒辦法使 VPN 正常運作，你仍然可以進行你的工作。 在很多其他的系統上，這麼做通常是不可能或是非常痛苦的事。 以 Perforce 為例，當你連不上伺服器時，你幾乎沒事可做。在 Subversion 和 CVS 中，你可以修改檔案，但是你沒辦法提交版本（只因為你連不上資料庫）。 這看起來可能不是什麼大問題，但是你可能會驚訝於 Git 能做到的事情有這麼大的差異。

在 Git 中所有的物件在儲存前都會被計算校驗碼（checksum）並以校驗碼參照物件。 這意味著你不可能瞞著 Git 對任何檔案或目錄進行修改。 此功能內建在 Git 底層並整合到它的設計哲學。 Git 更能夠馬上察覺傳輸時的遺失或是檔案的毀損。

Git 用來計算校驗碼的機制稱為 SHA-1 雜湊演算法。 一個校驗碼是由 40 個 16 進位的字母（0–9 和 a–f）所組成，Git 會根據檔案的內容和資料夾的結構來計算。 一個 SHA-1 校驗碼看起來如下所示：

你會 Git 中到處都看到校驗碼，因為校驗碼被 Git 到處使用。 事實上在 Git 的資料庫內，每個檔案都是用其內容的校驗碼來儲存，而不是使用檔名。

當你使用 Git，幾乎所有的動作都只是增加資料到Git的資料庫。 你很難藉此讓做出讓系統無法復原或者清除資料的動作。 在任何版本控制系統中，你尚未提交的修改都有可能會遺失或者搞亂。 但是只要你提交快照到 Git 後，很難會發生遺失的情況，特別是你定期將資料庫推送（push）到其它儲存庫時，就更不可能會弄丟資料。

這讓我們在使用 Git 的時候時可以像在玩玩具一樣，因為我們知道我們可以隨意操作而不會弄壞任何東西。 在 復原 中，我們會進一步討論 Git 如何儲存資料，以及你如何復原看似遺失的資料。

現在，請特別注意。 若你希望接下來的學習過程順利些，請務必記住以下這些關於 Git 的知識。 Git 會把你的檔案標記為三種主要的狀態：已提交（committed）、已修改（modified）及已預存（staged）。 已提交代表這檔案己安全地存在你的本地端資料庫。 己修改代表這檔案已被修改但尚未提交到本地端資料庫。 已預存代表這檔案將會被存到下次你提交的快照中。

這帶領我們到 Git 專案的三個主要區域：Git 資料夾、工作目錄（working directory）以及預存區（staging area）。

Git 資料夾是 Git 用來儲存你專案的後設資料及物件資料庫的地方。 這是 Git 最重要的部份，而且當你克隆一個其他電腦的儲存庫時，這個資料夾也會被同時複製。

工作目錄是專案被檢出的某一個版本。 這些檔案從 Git 目錄內被壓縮過的資料庫中拉出來並放在硬碟供你使用或修改。

預存區是一個單一檔案，一般來說放在 Git 目錄下，儲存關於下次提交的資訊。 有時它會稱為索引「index」，但現在更常被稱呼為預存區。

基本 Git 工作流程大致如下：

若檔案已被存於 Git 資料夾內，則稱為已提交。 若檔案先被修改，接著被增加到預存區域，則稱為已預存。 若檔案被檢出後有被修改，但未被預存，則稱為已修改。 在 Git 基礎 內你將會學到更多關於這些狀態的知識以及如何利用它們的優點或者直接略過預存步驟。

如果你想要透過二進位安裝程式安裝基本的 Git 工具集，你通常可以直接透過你所用的發行版（distribution）內建的基礎套件管理工具。 舉例來說，如果你使用的是 Fedora，你可以使用 yum：

如果你是使用 Debian 系列的發行版，如 Ubuntu，你可以使用 apt-get：

如果需要更多選擇，Git 官方網站上有更多其他的發行版中安裝 Git 的安裝步驟，網址為 http://git-scm.com/download/linux。

在 Mac 中安裝 Git 有很多種方法。 最簡單的方法應該就是直接安裝 Xcode 命令列開發者工具（Xcode Command Line Tools）。 在 Mavericks (10.9) 或更新版的系統中，你甚至可以直接在終端機中直接打入「git」指令。 如果系統發現你還沒安裝過，便會自動提示你進行安裝。

如果你希望安裝更新的版本，你也可以透過二進位安裝程式安裝。 在 Git 官方網站上有維護最新版的安裝程式可供下載，網址在 http://git-scm.com/download/mac。

你還可以透過 GitHub 的 Mac 安裝程式來安裝。 GitHub 的 Git 圖形化工具有提供相對應的選項讓你安裝 Git 命令列工具。 你可以從 GitHub for Mac 官方網站下載，網址在 http://mac.github.com。

在 Windows 中安裝 Git 也有很多種方式。 最正式的安裝程式在 Git 官方網站可供下載。 你只需要連到 http://git-scm.com/download/win 然後下載就會自動開始。 請注意這是一個名為 Git for Windows 的專案，與 Git 本身是互相獨立的。如果你需要更多資料，請查閱 http://git-for-windows.github.io/。

另一個安裝 Git 的簡單方法就是直接安裝 GitHub for Window。 這個安裝程式內已經預設提供 Git 的命令列版本和圖形化工具。 而且它也能夠完美搭配 Powershell，設定實體憑證快取和完整的 CRLF 設定。 我們將會在本書的其他章節學到這些事情，但我只想強調，這就是你需要的東西。 你可以直接從 GitHub for Windows 下載，網址在 http://windows.github.com。

某些人可能會發現從原始碼安裝 Git 反而比較好用，因為你可以拿到最新的 Git 版本。 通常二進位安裝程式都會落後於 Git 原始碼的版本，雖然 Git 近幾年已經逐漸成熟，兩者的版本差異可能不大。

如果你希望從原始碼安裝 Git，你需要擁有以下 Git 所需的函式庫：curl, zlib, openssl, expat 和 libiconv。 舉例來說，如果你的系統有 yum（例如 Fedora）或 apt-get（例如 Debian 系列的發行版），你可以使用其中一個指令來安裝這些最小相依關係（the minimal dependencies），這樣才有辦法安裝編譯並安裝 Git 可執行檔。

為了能夠建立這些格式（doc、html、info）的文件，你還需要安裝這些額外的相依關係（注意：RHEL 系列（像是 CentOS、Scientific Linux）的使用者必需 啟用 EPEL 版本庫，才能下載 docbook2X 套件）：

另外，如果你使用 Fedora 或 RHEL 系列，你還需要做這個：

這是因為所使用的檔名不同。（譯注: 此行命令是對 docbook2x-texi 做一個捷徑，將其「連結」到實際上所使用的 db2x_docbook2texi。）

當你成功的安裝所有必備的相依關係，你就可以繼續下一步：從以下其中一個地方抓回最新的 Git 原始碼 tarball 壓縮檔。 你可以從 Kernel.org 網站取得，網址在 https://www.kernel.org/pub/software/scm/git；或是在 GitHub 上面的鏡像，網址在 https://github.com/git/git/releases。 通常在 GitHub 網站上你會比較容易知道哪個原始碼是最新的；但是在 kernel.org 網站上會同時提供該檔案的數位簽章，以便你下載後對檔案進行驗證。

再來，編譯並安裝 Git：

當你安裝完以後，你就可以透過 Git 來取得 Git 最新的原始碼如下：

在你安裝 Git 後首先應該做的事是設定使用者名稱及電子郵件。 這一點非常重要，因為每次 Git 的提交會使用這些資訊，而且提交後不能再被修改：

再次提醒，若你有傳遞 --global 參數，只需要做這工作一次，因為在此系統，不論 Git 做任何事都會採用此資訊。 若你想指定不同的名字或電子郵件給特定的專案，只需要在該專案目錄內執行此命令，並確定未加上 --global 參數。

許多圖形使用者介面的工具會在你第一次使用它們時幫你做這工作。

現在你的識別資料已設定完畢，讀者可設定預設的文書編輯器，當 Git 需要你輸入訊息時會使用它。 預設情況下，Git 會使用系統預設的編輯器。

若你想指定不同的編輯器，例如：Emacs，可以執行下列指令：

如果你想要在 Windows 系統上使用 Notepad++ 做為編輯器，你可以執行下列步驟：

在 x86 系統上

在 x64 系統上

若你想檢查設定值，可使用 git config --list 命令列出所有 Git 在目前位置能找到的設定值：

你可能會看到同一個設定名稱出現多次，因為 Git 從不同的檔案讀到同一個設定名稱（例如：/etc/gitconfig 及 ~/.gitconfig）。 在這情況下，Git 會使用最後一個設定名稱的設定值。

你也可以輸入 git config <key> 來檢視某個設定目前的值：

若你打算使用 Git 來追蹤（track）現有的專案，只需要進入該專案的資料夾並執行：

這個命令將會建立一個名為 .git 的子資料夾，其中包含 Git 所有必需的倉儲檔案，也就是 Git 倉儲的骨架。 到現在這步驟為止，倉儲預設沒有追蹤任何檔案。 （想知道你剛建立的 .git 資料夾內有些什麼檔案，請參考Git Internals）

如果你的專案資料夾原本已經有檔案（不是空的），那麼建議你應該馬上追蹤這些原本就有的檔案，然後進行第一次提交。 你可以通過多次 git add 指令來追蹤完所有你想要追蹤的檔案，然後執行 git commit 提交：

進行這些動作應該不會花你太多時間。 到現在這步驟為止，你已經得到了一個追蹤若干檔案及第一次提交內容的 Git 倉儲。

若你想要取得現有 Git 倉儲的複本（例如：你想要開始協作的倉儲），那你需要使用的命令是 git clone。 若你熟悉其它像是 Subversion 的版本控制系統，你應該注意現在這個命令是克隆（clone），而非取出（checkout）。 這是 Git 和其他版本控制系統的重要差異：Git 並不僅只是取得專案最新的內容，而是把遠端倉儲內幾乎所有的資料都抓回來了。 專案歷史紀錄中，每個檔案的每個版本預設都會在你執行 git clone 時被拉取（pull）回來。 實際上，如果伺服器的硬碟損壞，你通常可以使用任何客戶端克隆的倉儲來將伺服器重建回原本克隆的狀態。（你可能遺失一些伺服器的掛勾程式 hooks，但你所有的版本資料都還會健在，請查看 在伺服器上佈署 Git 獲得更多資訊）

克隆倉庫的命令格式是 git clone [url]。 例如：若你想克隆名為 libgit2 的 Git linkable library，可以執行下列命令：

這指令將會建立名為「libgit2」的資料夾，並在這個資料夾下初始化一個 .git 資料夾，從遠端倉儲拉取所有資料，並且取出（checkout）專案中最新的版本。 若你進入新建立的 libgit2 資料夾，你將會看到專案的檔案都在裡面了，並且準備就緒等你進行後續的開發或使用。 若你想要將倉儲克隆到「libgit2」以外名字的資料夾，只需要再多指定一個參數即可：

這個命令做的事與上一個命令大致相同，只不過在本地創建的倉庫名字變為 mylibgit。

Git 支援多種數據傳輸協定。 上一個範例採用 https:// 協定，但你可能會看過 git:// 或 user@server:path/to/repo.git 等使用 SSH 傳輸的協定。 在 在伺服器上佈署 Git 章節將會介紹這些協定在伺服器端如何配置及使用，以及各種方式的優缺點。

git status 命令是用來偵測哪些檔案處在什麼樣的狀態下的主要工具； 如果你在克隆之後直接執行該命令，應該會看到類似以下內容：

這意味著你有一個乾淨的工作目錄——換句話說，已追蹤的檔案沒有被修改； Git 也沒有看到任何未追蹤檔案，否則它們會在這裡被列出來； 最後，這個命令告訴你目前在哪一個分支上，也告訴你它和伺服器上的同名分支是同步的。 到目前為止，該分支一直都是預設的「master」，在這裡你先不用擔心它， 使用 Git 分支 會詳細地介紹「分支（branch）」和「參照（reference）」。

假設你在專案中新增一個檔案，例如：一個簡單的 README 檔案； 如果該檔案先前並不存在，執行 git status 命令後，你會看到未追蹤檔案：

你可以看到新增檔案 README 尚未被追蹤，因為它被列在輸出訊息的「Untracked files」欄位下方； 基本上「未追蹤」表示 Git 發現這個檔案在上次的快照（提交）中並不存在；Git 並不會將此檔案納入你的提交快照，除非你明確地告訴 Git 要這麼做； 它會這樣做是為了避免你意外地將一些二進位暫存檔或其它你並不想要的檔案納入版本控制。 讓我們開始追蹤 README 檔案，因為你確實想要將它開始納入版本控制。

要開始追蹤一個新的檔案，可以使用 git add 命令； 要開始追蹤 README 檔案，你可以執行：

如果再次執行檢查狀態命令，可以看到 README 檔案現在是準備好被提交的「已追蹤」和「已預存」狀態：

由於它放在「Changes to be committed」欄位下方，你可以得知它已經被預存， 如果你在此時提交，在執行 git add 的當下所加進來的檔案版本就會被記錄在歷史快照中； 你或許會想到之前執行 git init 後也有執行過 git add (files)——那就是開始追蹤目錄內的檔案。 git add 命令接受「檔案」或「目錄」做為路徑名稱；如果是目錄，該命令會用遞迴的方式加入那個目錄下所有的檔案。

讓我們修改一個已追蹤檔案； 假設你修改了一個先前已追蹤的檔案 CONTRIBUTING.md，接著再次執行 git status，你會看到類似以下文字：

CONTRIBUTING.md 檔案出現在「Changes not staged for commit」欄位下方——代表著位於工作目錄的已追蹤檔案已經被修改，但尚未預存； 要預存該檔案，你可執行 git add 命令； git add 是一個多重用途的指令——用來「開始追蹤」檔案、「預存」檔案以及做一些其它的事，像是「標記合併衝突（merge-conflicted）檔案為已解決」。 比起「把這個檔案加進專案」，把它想成「把檔案內容加入下一個提交中」會比較容易理解。 現在，讓我們執行 git add 將 CONTRIBUTING.md 檔案預存起來，並再度執行 git status：

這兩個檔案目前都被預存，而且將會成為你下次提交的內容； 此時，假設在提交前你想起要對 CONTRIBUTING.md 再做一個小修改， 你再次開啟檔案並修改它，然後準備提交； 然而，當我們再次執行 git status：

見鬼了？ 現在 CONTRIBUTING.md 同時被列在已預存「及」未預存。 這怎麼可能？ 原來 Git 在你執行 git add 命令時，的確將當時的檔案內容預存起來； 如果你現在提交，最後一次執行 git add 命令時，那個當下的 CONTRIBUTING.md 的版本會被提交，而不是在提交時你在工作目錄所看到的檔案版本被提交； 如果你在 git add 後修改檔案，你必需再次執行 git add 預存最新版的檔案：

雖然 git status 輸出內容相當全面，但也相當囉嗦； Git 另外提供一個簡潔輸出的選項，因此你可以以一種較精簡的方式來檢視你的修改； 如果你執行 git status -s 或 git status --short，你可以從該命令得到一個相當簡單的輸出內容：

未追蹤的新檔案在開頭被標示為 ??、被加入預存區的新檔案被標為 A、已修改檔案則是 M 等等。 標記有二個欄位——左邊欄位用來指示「預存區」狀態，右邊欄位則是「工作目錄」狀態。 所以在這個範例中，在工作目錄中的檔案 README 是已修改的，但尚未被預存；而 lib/simplegit.rb 檔案則是已修改且已預存的； Rakefile 則是曾經修改過也預存過，但之後又再次修改，所以總共有二次修改，一個有預存一個沒有。

通常你會有一類檔案不想讓 Git 自動加入，也不希望它們被顯示為未追蹤， 這些通常是自動產生的檔案，例如：日誌檔案或者編譯系統產生的檔案； 在這情況下，你可以新建一個名為 .gitignore 的檔案，在該檔中列舉符合這些檔名的模式（pattern）。 以下是一個 .gitignore 範例檔內容：

第一列告訴 Git 忽略任何副檔名為「.o」或「.a」的檔案，它們可能是編譯系統建置程式碼時所產生的目的檔及連結檔； 第二列告訴 Git 忽略所有檔名以波浪號（~）結尾的檔案，這種檔案通常被用在很多文字編輯器中，例如：Emacs 把它用在暫存檔； 你可能也想忽略 log、tmp、pid 目錄、自動產生的文件等等； 在你要開始做事之前將 .gitignore 設定好通常是一個不錯的主意，這樣你就不會意外地將實際上並不想追蹤的檔案提交到你的 Git 版本庫。

編寫 .gitignore 檔案的模式規則如下：

Glob 模式就像是 Shell 所使用的簡化版正規運算式（regular expressions）； 一個星號（*）匹配零個或多個字元、[abc] 匹配中括弧內的其中一個字元（此例為 a、b、c）、問號（?）匹配單一個字元、中括孤內的字以連字號連接（如：[0-9]）用來匹配任何在該範圍內的字元（此例為 0 到 9）； 你也可以使用二個星號用來匹配巢狀目錄；a/**/z 將會匹配到 a/z、a/b/z、a/b/c/z 等等。

以下是另一個 .gitignore 範例檔案：

如果 git status 命令提供的資訊對你來說太過簡略——你要想精確地知道你修改了什麼，而不只是那些檔案被修改——你可以使用 git diff 命令； 稍後我們會更詳盡講解 git diff 命令，然而大部分你在使用它的時候只是為了瞭解兩個問題：已修改但尚未預存的內容是哪些？ 已預存而準備被提交的內容又有哪些？ 儘管 git status 命令透過列出檔名的方式大略回答了這些問題，但 git diff 可顯示檔案裡的哪些列被加入或刪除——如同以往地以補綴（patch）格式呈現。

假設你再次編輯並預存 README 檔案，接著修改 CONTRIBUTING.md 檔案卻未預存它， 如果你執行 git status 命令，你會再次看到類似以下資訊：

想瞭解尚未預存的修改，輸入不帶其它參數的 git diff：

這命令會比對「工作目錄」和「預存區」之間的版本， 然後顯示尚未被存入預存區的修改內容。

如果你想檢視你已經預存而接下來將會被提交的內容，可以使用 git diff --staged； 這個命令比對的對象是「預存區」和「最後一次提交」。

很重要且需要注意的一點是 git diff 不會顯示最後一次提交後的所有變更——只會顯示未預存的變更； 這會讓人困惑，因為如果你預存了所有的變更，git diff 不會輸出任何內容。

舉其它例子，如果你預存 CONTRIBUTING.md 檔案後又編輯它，你可以使用 git diff 檢視檔案中哪些變更是已預存的、哪些是尚未預存的。 如果它看起來像這樣：

現在你可以使用 git diff 來檢視哪些部分是仍然未預存的：

以及使用 git diff --cached 檢視哪些部分是已預存的（--staged 和 --cached 是同義選項）：

現在你的預存區已被建構成你想要的，你可以開始提交你的變更； 記住：任何未預暫存的檔案——新增的、已修改的，自從你編輯它們卻尚未用 git add 預存的——將不會納入本次的提交中； 它們仍以「已修改」的身份存在磁碟中。 在目前情況下，假設你上次執行 git status 時，你看到所有檔案都已經被預存，因此你準備提交你的變更。 最簡單的提交方式是輸入 git commit：

這麼做會啟動你選定的編輯器 （由你的 Shell 的 $EDITOR 環境變數所指定——通常是 vim 或 emacs；你也可以如同 開始 所介紹的，使用 git config --global core.editor 命令指定任何一個你想使用的）。

編輯器會顯示如下文字（此範例為 Vim 的畫面）：

你可以看到預設的提交訊息中包含最近一次 git status 的輸出並以註解方式呈現，以及最上方有一列空白列； 你可以移除這些註解後再輸入提交訊息，或者保留它們以提醒你現在正在提交什麼樣的內容。 （如果想對你已經修改的內容得到更明確的提示，可以在 git commit 上加上 -v 選項； 這麼做連修改的差異內容也會被放到編輯器中，如此你便可以精確地看到你正在提交的修改內容。） 當你關閉編輯器，Git 會利用這些提交訊息（註解和差異內容會被濾除）產生新的提交。

另一種方式則是在 commit 命令的 -m 選項後方直接輸入提交訊息，如下：

現在你已經建立了你的第一個提交！ 你可從輸出訊息看到此提交相關資訊：提交到哪個分支（master）、提交的 SHA-1 校驗碼（463dc4f）、有多少檔案被更動，以及統計此提交有多少列被新增和被移除。

記住：那個提交記錄了你放在預存區的快照。 任何你尚未預存的已修改檔案仍然安好地在那裡，你可以做另一次提交來把它加入到你的歷史中； 每一次提交時，你都正在對專案記錄一個快照，可以在之後用來「復原」或「比對」。

雖然「預存區」的用法讓你能夠很有技巧地且精確地提交你想記錄的內容而意外地好用，但有時候它也比你實際需要的工作流程要繁瑣得多； 如果你想跳過預存區，Git 提供了一個簡易的捷徑， 在 git commit 命令加上 -a 選項，使 Git 在提交前自動預存所有已追蹤的檔案，讓你略過 git add 步驟：

請留意這種使用情況：在提交之前，你並不需要執行 git add 來預存 CONTRIBUTING.md 檔案； 那是因為 -a 選項會納入所有已變更的檔案； 很方便，但請小心，有時候它會納入你並不想要的變更。

要從 Git 中刪除一個檔案，你需要將它從已追蹤檔案中移除（更準確地說，是從預存區中移除），然後再提交； git rm 命令可完成此工作，它同時也會將該檔案從工作目錄中移除，如此它之後也不會身為未追蹤檔案而被你看到。

如果你僅僅是將檔案從工作目錄中移除，那麼它會被列在 git status 輸出內容的「Changed but not updated」（也就是「未預存」）欄位下面：

如果你接著執行 git rm，它會預存該檔案的移除動作：

下一次提交時，該檔案將會消失而且不再被追蹤； 如果你修改了檔案且已經把修改內容加入索引中（譯注：「加入索引」和「預存」是同義詞），你必需使用 -f 選項才能強制將它移除； 這是一種為了避免已記錄的快照意外被移除後再也無法使用 Git 復原的保護機制。

另一個有用的技巧是保留工作目錄的檔案，但將它從預存區中移除； 換句話說，你或許想保留在磁碟機上的檔案但不希望 Git 再繼續追蹤它； 當你忘記將某些檔案加到 .gitignore 中而且不小心預存它的時候會特別用有，像是不小心預存了一個大的日誌檔案或者一堆 .a 已編譯檔案。 加上 --cached 選項可做到這件事：

你可將「檔案」、「目錄」、「file-glob 模式」做為參數傳給 git rm 命令， 那意味著你可以做類似下面的事：

注意：星號 * 前面有反斜線（\）； 這是必須的，因為 Git 在你的 Shell 檔名擴展（filename expansion）之上另外有自己的檔名擴展； 此命令會移除在 log/ 所有副檔名為 .log 的檔案。 或者你也可以做像下面的事：

此命令會移除所有以 ~ 結尾的檔案。

Git 不像其它 VCS 系統，它並不會明確地追蹤檔案的移動； 如果你在 Git 中重新命名一個檔案，並不會有任何 Git 後設資料記錄這個動作以辨別你曾經重新命名過檔案； 然而 Git 可以在檔案移動後很聰明地將它們找出來——我們稍後會對偵測檔案的移動再多做一點說明。

因此 Git 有一個 mv 命令反而有點令人困惑； 如果你想要在 Git 中重新命名一個檔案，你可以執行以下命令：

並且它運作地想當好； 事實上，如果你執行類似以下的動作然後檢視一下狀態，你將看到 Git 將該檔案視為一個重新命名過的檔案：

其實，它相當於執行下列命令：

Git 會在背後判斷檔案被重新命名，因此不管是用上述方法還是用 mv 命令並沒有差別； 實際上唯一不同的是 mv 是一個命令，而不是三個——它只是個方便的功能。 更重要的是你可以使用任何你喜歡的工具來重新命名一個檔案，然後在提交前才使用 add/rm。

除了輸出格式的選項以外，git log 還有一些有用的輸出限制選項——也就是讓你能夠只顯示一個子集合的提交； 你先前已看過其中一個——用 -2 選項只顯示最後二筆提交， 事實上，你可以用 -<n>，其中 n 是任意整數，用來顯示最後 n 筆提交； 實際上，你可能不太會那麼常用到它，因為 Git 預設把輸出導向分頁器，所以你一次只能看到一頁的日誌輸出內容。

然而，像 --since 和 --until 這些限制時間的選項就很有用； 例如，以下命令列出最近兩週以來的提交：

這個命令支援各種格式——你可以指定特定的日期格式（例如："2008-01-15"），或者相對日期格式（例如："2 years 1 day 3 minutes ago"）。

你也可以過濾列表中符合某些搜尋條件的提交； --author 選項允許你過濾特定作者，而 --grep 選項允許你以關鍵字搜尋提交訊息。 （注意：如果你想要同時比對作者及提交訊息，你必需加上 --all-match，否則只要滿足其中一個條件的提交都會被列出來。）

另一個實用的選項是 -S，用來尋找所修改的內容中被加入或移除某字串的提交； 擧例，如果你想要找出最後一個有加入或移除某個特定函數參照的提交，你可以使用：

最後一個實用的 git log 過濾選項是路徑， 如果你指定一個目錄或檔名，你可以列出只對這些檔案有修改記錄的提交； 這個選項永遠放在最後一個，並且通常使用二個連接號（--）將路徑與其它選項隔開。

我們在 Options to limit the output of git log 中列出這些選項和一些其它常用選項供你參考。

例如：如果你想檢視 Git 原始碼的測試檔案中（譯註：它們都放在資料夾 t/），由 Junio Hamano 在 2008 年 10 月份所提交，但不包含「合併提交」的提交。可執行以下的命令：

在 Git 原始碼接近 40,000 筆提交歷史記錄中，這個命令列出其中符合條件的 6 筆。

接下來的兩節會展示如何操作預存區和工作目錄中已修改的檔案； 用來顯示這二個區域狀態的命令也會好心地提示你如何做復原操作， 例如：假設你已經修改了二個檔案，並且想要分別提交它們，但是你卻意外地使用 git add * 把它們二個都預存了， 要如何將其中一個「移出預存區（unstage）」呢？ git status 命令提示你：

在「Changes to be committed」文字正下方，說明了使用 git reset HEAD <file>... 將檔案移出預存區； 因此，讓我們依循該建議將 CONTRIBUTING.md 檔案移出預存區：

這個命令有一點奇怪，不過它的確可行； CONTRIBUTING.md 檔案現在又回到了「修改」但「未預存（unstaged）」的狀態。

關於 git reset 命令，到目前為止所有你需要知道的就只有這個神奇用法； 我們將在 Reset Demystified 中深入了解 reset 更多的細節，包括「它可以做什麼」以及「如何操控它做一些真正有趣的事情」。

當你不想要保留 CONTRIBUTING.md 檔案的修改時該怎麼辦？ 你如何才能輕易地復原它——將它還原到上次提交時的樣子（或最初克隆時、或當初放到工作目錄時的版本）？ 很幸運的，git status 也告訴你該如何做； 在上一個範例的輸出中，有修改而未預存的內容長得像這樣：

它相當明確地提示你如何捨棄工作目錄所做的修改， 讓我們跟著提示做：

你可以看到那些修改已經被還原了。

如果你仍然想保留那個檔案所做的修改，但是某個當下需要先復原檔案，我們將會在 使用 Git 分支 中介紹「收藏（stashing）」和「分支（branching）」，一般而言它們是比較好的做法。

切記，在 Git「已提交」的任何東西幾乎總是能夠被復原的， 即使是在被刪除的分支上曾經出現過的提交，或者因為 --amend 而被覆蓋掉的提交，它們都是可以被復原的（詳見 Data Recovery 以了解資料復原）； 然而，從來沒被提交過的內容，失去後大概就沒辦法再救回來了。

使用 git remote 命令可以檢視你已經設定好的遠端版本庫， 它會列出每個遠端版本庫的「簡稱」。 如果你克隆（clone）了一個遠端版本庫，你至少看得到「origin」——它是 Git 給定的預設簡稱，用來代表被克隆的來源。

你也可以指定 -v 選項來顯示 Git 用來讀寫遠端簡稱時所用的網址。

如果遠端版本庫不止一個，這個命令會將它們全部列出來。 例如，一個版本庫內連結了許多其它協作者的遠端版本庫，可能看起來就像這樣：

這意味著我們可以很輕鬆地拉取任何協作者的貢獻； 我們可能對其中某些遠端版本庫還擁有推送權限，不過我們不會在這裡詳述這個部分。

注意：這些遠端版本庫使用了不同的通訊協定；我們將會在 在伺服器上佈署 Git 對它有更多的說明。

我們在之前的章節中已經提過並給了一些範例來說明 clone 命令如何隱式地為你加入 origin 遠端； 而在這裡將說明如何「明確地」新增一個遠端。 選一個你可以輕鬆引用的簡稱，用來代表要新增的遠端 Git 版本庫，然後執行 git remote add <簡稱> <url> 來新增它：

現在你可以在命令列中使用 pb 這個字串來代表整個網址； 例如，如果你想從 Paul 的版本庫中取得所有資訊，而這些資訊並不存在於你的版本庫中，你可以執行 git fetch pb：

現在 Paul 的 master 分支可以在本地端透過 pb/master 存取到（譯註：把 pb/master 想成 Paul 的 master 在你本地端的「分身」——實際上它被稱為「遠端追蹤分支（remote-tracking branch）」）——你可以把它合併（merge）到你的其中一個分支；或者，如果你想要檢視它的話，可以在它身上檢出（checkout）一個本地分支。 （我們將會在 使用 Git 分支 中詳細介紹什麼是分支以及如何使用它們。）

如同你剛剛所看到的，要從你的遠端專案中取得資料，你可以執行：

這個命令會連到遠端專案，然後從遠端專案中將你還沒有的資料全部拉下來； 執行完成後，你應該會有那個遠端版本庫中所有分支的參照（reference）（譯註：再次強調，遠端的分支在本地端的分身——遠端追蹤分支），可以隨時用來合併或檢視。

如果你克隆了一個版本庫，clone 命令會自動增加一個「origin」來代表遠端版本庫； 所以，git fetch origin 會獲取（fetch）在你克隆（或者最後一次獲取）之後任何被推送到伺服器上的新的工作內容。 很重要的一點是：git fetch 命令只會下載資料到你的版本庫——它並不會自動合併你的任何工作內容，也不會自動修改你正在修改的東西； 當你準備好合併你的工作內容時，你必需用手動的方式進行合併。

如果你的目前分支被設定為「追蹤」遠端上的分支（閱讀下一節以及 使用 Git 分支 以了解更多資訊），你便可使用 git pull 命令來自動「獲取」並「合併」那個遠端分支到你目前的分支裡去； 由於 git clone 命令會「自動地」將本地分支 master 設定為「追蹤」遠端上的 master（無論預設分支叫什麼名稱。譯註：只要是預設分支都會自動設定追踨行為，而 master 常常是預設分支），這可能會讓你有比較輕鬆自在的工作流程： 只要執行 git pull 通常就會從你最初克隆的伺服器上獲取資料，然後試著自動合併到目前的分支。

當你想分享你的專案成果時，你必需將它推送到上游。 推送的命令很簡單：git push [remote-name] [branch-name]。 如果你想要將 master 分支推送到 origin 伺服器上時（再次說明，克隆時通常會自動地幫你設定好 master 和 origin 這二個名稱），那麼你可以執行這個命今將所有你完成的提交（commit）推送回伺服器上。

只有在你對克隆來源的伺服器有寫入權限，並且在這個當下還沒有其它人推送過，這個命令才會成功； 如果你和其它人同時做了克隆，然後他們先推送到上游，接著換你推送到上游，毫無疑問地你的推送會被拒絕； 你必需先獲取他們的工作內容，將其整併到你之前的工作內容，如此你才會被允許推送。 閱讀 使用 Git 分支 以了解更多關於「如何推送到遠端伺服器」的詳細資訊。

如果你想要對一個特定遠端檢視更多資訊，你可以使用 git remote show [remote-name] 命令。 如果你在執行這個命令中使用特定的簡稱，例如 origin，你會得到下面這個類似的訊息：

它同時列出了遠端版本庫的網址和「追蹤分支（tracking branch）」資訊。 這個命令很有用地告訴你：目前分支是 master（譯注：HEAD 意味著目前的），如果你執行 git pull，它會在獲取所有遠端參照之後，自動將遠端的 master 合併到你的 master 分支。 它也會列出所有已抓下來的遠端參照（譯註：此例中指「master tracked」和「dev-branch tracked」）。

這是一個你很可能會遇到的簡單例子； 然而，當你更重度地使用 Git 後，你將會從 git remote show 中看到更多的資訊：

這個命令顯示了當你在特定的分支上執行 git push 時，它將自動推送到哪一個遠端分支； 它也顯示了：哪些遠端分支是在你的本地端還沒有的（譯註：new 屬性）、哪些你曾獲取過的遠端分支已經在遠端上被移除了（譯註：stale 屬性）、哪些本地分支是有能力在執行 git pull 後自動和它們的遠端追蹤分支合併。

你可以執行 git remote rename 來重新命名遠端的簡稱。 例如：如果你想要將 pb 重新命名為 paul，你可以這樣使用 git remote rename：

值得一提的是：它會更新所有遠端追蹤分支的名稱； 曾經用來被參考的遠端追蹤分支 pb/master 現在改名為 paul/master。

如果你因為某些原因想要移除一個遠端——你搬動了伺服器、或者不再使用某個特定的鏡像、或者某個貢獻者不再貢獻了——你可以執行 git remote rm：

想要列出 Git 中所有標籤的方法非常直覺。 只要輸入 git tag 如下：

這個指令將依字母序列出所有標籤；雖然說標籤用什麼方式列出不是很重要。

你也可以使用特定的 pattern 來搜尋標籤。 舉例來說，在 Git 原始碼的版本庫中，已經包含了超過 500 個標籤。 如果你只想看到 1.8.5 系列的標籤，你可以執行以下指令：

Git 主要使用兩種類型的標籤：輕量級標籤和有註解的標籤。

一個輕量級的標籤就像是一個不會移動的分支——這個標籤只會指向一個特定的提交。

然而，有註解的標籤，會在 Git 的資料庫中儲存成完整的物件。 它們將被計算校驗碼；包含貼標籤那個人的名字、電子郵件和日期；能夠紀錄一個標籤訊息；並且可以簽署及透過 GNU Privacy Guard (GPG) 驗證。 通常建議你可以建立一個有註解的標籤，以便你可以保留跟這個標籤有關的所有資訊；但是你如果只想要一個暫時的標籤，或是因為某些原因不想保留額外的資訊，你也可以只用輕量級標籤。

建立一個有註解的標籤很簡單。 最簡單的方法是在你建立標籤時，同時指定 -a 的選項如下：

指令中的 -m 選項後面同時指定了一個標籤訊息，這個訊息會和這個標籤一起保存。 如果你沒有為標籤指定一個訊息，那麼 Git 會開啟你的編輯器以便你輸入。

當你使用 git show 指令時，你可以查看標籤的資訊，還有這個標籤所標記的提交資訊如下：

這樣就可以在提交資訊前顯示出標籤的資訊、標籤被建立的時間以及標籤的訊息。

另外一種能標記提交的標籤是輕量級標籤。 這基本上是把該提交的校驗碼存在一個檔案中，不包含其他資訊。 如果想要建立一個輕量級的標籤，不要指定 -a、-s 或 -m 的選項如下：

此時如果對該標籤使用 git show，你將不會看到這個標籤的額外資訊。 這個指令就只會顯示標籤所在的提交資訊：

你也可以對過去的提交貼標籤。 假設你的提交歷史看起來如下：

現在，假設你忘記在專案的「updated rakefile」提交貼 v1.2 的標籤。 你可以在後來再補貼標籤。 要在那個提交上面貼標籤，你需要在指令後面指定那個提交的校驗碼（可以省略後半段）：

你可以看到你已經在那個提交上面貼標籤了：

git push 指令預設不會傳送標籤到遠端伺服器。 在你建立標籤後，你必須明確的要求 Git 將標籤推送到共用的伺服器上面。 這個動作就像是在分享遠端分支一樣——你可以執行 git push origin [tagname]。

如果想要一次推送很多標籤，也可以在使用 git push 指令的時候加上 --tags 選項。 這將會把你所有不在伺服器上面的標籤傳送給遠端伺服器。

現在，當其他人從版本庫克隆或拉取時，他們就能同時拿到你所貼的標籤，

在 Git 中你不能真的檢出一個標籤，因為它們並不能像分支一樣四處移動。 如果你希望工作目錄和版本庫中特定的標籤版本完全一樣，你可以使用 git checkout -b [branchname] [tagname] 在該標籤上建立一個新分支：

當然，如果在建立新分支以後又進行了一次提交，version2 分支將會和 v2.0.0 標籤有所差異，因為這個分支已經因為你的提交而改變了，請特別小心。

建立一個新分支會發生什麼事呢？ 答案很簡單，建立一個新的、可移動的指標； 比如新建一個 testing 分支， 可以使用 git branch 命令：

這會在目前提交上新建一個指標。

Git 如何知道你目前在哪個分支上工作的呢？ 其實它保存了一個名為 HEAD 的特別指標； 請注意它和你可能慣用的其他 VCSs 裡的 HEAD 概念大不相同，比如 Subversion 或 CVS； 在 Git 中，它就是一個指向你正在工作中的本地分支的指標（譯注：HEAD 等於「目前的」）， 所以在這個例子中，你仍然在 master 分支上工作； 執行 git branch 命令，只是「建立」一個新的分支——它並不會切換到這個分支。

你可以很輕鬆地看到分支指標指向何處，只需透過一個簡單的 git log 命令， 加上 --decorate 選項。

你可以看到「master」和「testing」分支就顯示在 f30ab 提交旁邊。

要切換到一個已經存在的分支，你可以執行 git checkout 命令， 讓我們切換到新的 testing 分支：

這會移動 HEAD 並指向 testing 分支。

這樣做有什麼意義呢？ 好吧！讓我們再提交一次：

非常有趣，現在 testing 分支向前移動了，而 master 分支仍然指向當初在執行 git checkout 時所在的提交， 讓我們切回 master 分支看看：

這條命令做了兩件事， 它把 HEAD 指標移回去並指向 master 分支，然後把工作目錄中的檔案換成 master 分支所指向的快照內容； 也就是說，現在開始所做的改動，將基於專案中較舊的版本，然後與其它提交歷史分離開來； 它實際上是取消你在 testing 分支裡所做的修改，這樣你就可以往不同方向前進。

讓我們做一些修改並再次提交：

現在你的專案歷史開始分離了（詳見 分離的歷史）； 你建立並切換到新分支，在上面進行了一些工作，然後切換回到主分支進行了另外一些工作， 雙方的改變分別隔離在不同的分支裡：你可以在不同分支裡反覆切換，並在時機成熟時把它們合併到一起； 而所有這些工作只需要簡單的 branch、checkout、commit 命令。

你一樣可以從 git log 中輕鬆地看出這件事， 執行 git log --oneline --decorate --graph --all，它會印出你的提交歷史，顯示你的分支指標在哪裡，以及歷史如何被分離開來。

由於 Git 分支實際上只是一個檔案，該檔案內容是這個分支指向的提交的雜湊值（40 個字元長度的 SHA-1 字串），所以建立和銷毀一個分支就變得非常廉價； 新建一個分支就是向一個檔寫入 41 個位元組（40 個字元外加一個換行符號）那樣地簡單和快速。

這樣的分支功能和大多數舊 VCS 的分支功能形成了鮮明的對比，有些分支功能甚至需要複製專案中全部的檔案到另一個資料夾， 而根據專案檔案數量和大小的不同，可能花費的時間快則幾秒，慢則數分鐘；而在 Git 中幾乎都在瞬間完成。 還有，因為每次提交時都記錄了親代資訊，將來要合併分支時，它通常會幫我們自動並輕鬆地找到適當的合併基礎； 這樣子的特性在無形間鼓勵了開發者頻繁地建立和使用分支。

讓我們來瞧一瞧為什麼你應該要這麼做。

首先，我們假設你正在開發你的專案，並且已經有一些提交（commit）了。

無論你的公司使用的議題追蹤系統（issue-tracking system）是哪一套，你決定要修正其中的議題 #53； 要同時新建並切換到新分支，你可以在執行 git checkout 時加上 -b 選項：

它相當於下面這兩條命令：

你開始開發網站，並做了一些提交； 因為你檢出（checkout）了這個分支（也就是 HEAD 指標正指向它），iss53 分支也隨之向前推進：

現在你接到電話，那個網站有一個問題需要立即修正； 有了 Git ，你就不用把你的緊急修正連同 iss53 尚未完成的內容一起部署（deploy）到正式環境；你也不用為了正確地套用修正而先花一大堆功夫回復之前 iss53 的修改； 唯一需要做的只是切換回發佈產品用的 master 分支。

然而，在切換分支之前，留意一下你的工作目錄或預存區（staging area）裡是否有還沒提交的內容，它可能會和你即要檢出的分支產生衝突（conflict），Git 會因此而不讓你切換分支； 所以切換分支的時候最好先保持一個乾淨的工作區域。 稍後會在 Stashing and Cleaning 中介紹幾個繞過這種問題的辦法（分別叫做「使用收藏（stashing）」和「提交的修訂方法（commit amending）」）。 目前先讓我們假設你已經提交了所有的變更，因此你可以切回 master 分支了：

此時工作目錄中的內容和你在解決問題 #53 之前的內容一模一樣，你可以集中精力進行緊急修正了； 很重要的一點需要牢記：當你切換分支時，Git 會重置（reset）工作目錄內容，就像回到你在這個分支最後一次提交後的內容， 它會自動地增加、刪除和修改檔案以確保工作目錄的內容和當時的內容完全一樣。

接下來開始緊急修正； 讓我們建立一個緊急修正用的分支來進行工作，直到完成它：

你可以跑一些測試以確保該修正是你想要的，然後切回 master 分支並把它合併進來，再部署到產品上； 用 git merge 命令來進行合併：

注意合併時有一個「Fast-forward」字眼； 由於你要合併的分支 hotfix 所指向的提交 C4 直接超前了提交 C2，Git 於是簡單地把分支指標向前推進； 換句話說，如果想要合併的提交可以直接往回追溯歷史到目前所在的提交，Git 會因為沒有需要合併的工作而簡單地把指標向前推進——這就是所謂的「快進（fast-forward）」。

現在你的修改已經含在 master 分支所指向的提交的快照中，你可以部署該修正了。

在那個超級重要的修正被部署以後，你準備要切回到之前被中斷而正在做的工作； 然而在那之前，你可以先刪除 hotfix，因為你不再需要它了——master 也指向相同的提交； 使用 git branch 的 -d 選項執行刪除操作：

現在你可以切回到之前用來解決議題 #53 且仍在進展中的分支以繼續工作：

這裡值得注意的是之前 hotfix 分支的修改內容尚未包含到 iss53 分支的檔案中； 如果需要納入那個修正，你可以用 git merge master 把 master 分支合併到 iss53 分支；或者等 iss53 分支完成之後，再將它合併到 master。

你已經完成了議題 #53 的工作，並準備好將它合併到 master 分支； 要完成這件事，你需要將 iss53 分支合併到 master 分支，實際操作和之前合併 hotfix 分支時差不多， 只需切回合併目的地的 master 分支，然後執行 git merge 命令：

這次的合併和之前合併 hotfix 的情況看起來有點不一樣； 在這種情況下，你的開發歷史是從一個較早的點便開始分離開來， 由於目前所在的提交（譯註：C4）並不是被合併的分支（譯註：iss53，它指向 C5）的直接祖先，Git 必需進行一些處理； 就此例而言，Git 會用兩個分支末端的快照（譯註：C4、C5）以及它們的共同祖先（譯註：C2）進行一次簡單的三方合併（three-way merge）。

不同於將分支指標向前推進，Git 會對三方合併後的結果產生一個新的快照，並自動建立一個指向這個快照的提交（譯註：C6）。 這個提交被稱為「合併提交（merge commit）」，特別的是它的親代（parent）超過一個（譯註：C4 和 C5）。

值得一提的是 Git 會決定哪個共同祖先才是最佳合併基準；這一點和一些較舊的版控工具有所不同，像是 CVS 或 Subversion（1.5 以前的版本），它們需要開發者自己手動找出最佳合併基準； 這讓 Git 的合併操作比起其他系統都要簡單許多。

既然你的工作成果已經合併了，也就不再需要 iss53 分支了， 你可以在議題追蹤系統中關閉該議題，然後刪除這個分支：

有時候合併過程並不會如此順利， 如果在不同的分支中都修改了同一個檔案的同一部分，Git 就無法乾淨地合併它們； 如果你在解決議題 #53 的過程中修改了 hotfix 中也修改過的部分，將得到類似下面的「合併衝突」結果：

Git 沒有自動產生新的合併提交， 它會暫停下來等你解決（resolve）衝突； 在合併衝突發生後的任何時候，如果你要看看哪些檔案還沒有合併，可以使用 git status：

它會列出所有有合併衝突且仍未解決的檔案（譯註：列在 Unmerged paths: 下面）； Git 會在有衝突的檔案裡加入標準的「衝突解決（conflict-resolution）」標記，因此你可以手動開啟它們以解決這些衝突； 你的檔案會包含類似下面這樣子的區段：

可以看到 ======= 隔開的上半部分是 HEAD（即 master 分支，在執行合併命令前所切換過去的分支）中的內容，下半部分則是在 iss53 分支中的內容； 解決衝突的辦法無非是二選一，或者由你自己合併內容； 比如你可以把這整段內容替換成以下內容而解決這個衝突：

這個解決方案分別採納了兩個分支中的各一部分內容，並且完整地移除了 <<<<<<<、======= 和 >>>>>>> 這些標記行。 在解決了每個衝突檔案裡的每個衝突後，對每個檔案執行 git add 會將它們標記為已解決狀態， 因為預存（stage）動作代表了衝突已經解決。

如果你想用圖形介面的工具來解決這些衝突，你可以執行 git mergetool，它會呼叫一個適當的視覺化合併工具並引導你解決衝突：

如果不想用預設的合併工具（因為在 Mac 上執行了該命令，Git 預設選擇了 opendiff），你可以在「one of the following tools」列表中找到可使用的合併工具， 然後只要輸入你想使用的工具名稱即可。

退出合併工具以後，Git 會詢問你合併是否成功， 如果回答「是」，它會幫你把相關檔案預存起來，將狀態標記為已解決； 你可以再次執行 git status 來確認所有衝突都已經解決：

如果你滿意這個結果，並且確認了所有衝突都已經解決也預存了，就可以用 git commit 來完成這次合併提交； 預設的提交訊息看起來像這樣：

如果解決衝突的理由不是那麼明顯，或是想要幫助將來的人理解為何你要這樣解決衝突，你可以在訊息中提供更多的細節來說明。

Because Git uses a simple three-way merge, merging from one branch into another multiple times over a long period is generally easy to do. This means you can have several branches that are always open and that you use for different stages of your development cycle; you can merge regularly from some of them into others.

Many Git developers have a workflow that embraces this approach, such as having only code that is entirely stable in their master branch – possibly only code that has been or will be released. They have another parallel branch named develop or next that they work from or use to test stability – it isn’t necessarily always stable, but whenever it gets to a stable state, it can be merged into master. It’s used to pull in topic branches (short-lived branches, like your earlier iss53 branch) when they’re ready, to make sure they pass all the tests and don’t introduce bugs.

In reality, we’re talking about pointers moving up the line of commits you’re making. The stable branches are farther down the line in your commit history, and the bleeding-edge branches are farther up the history.

It’s generally easier to think about them as work silos, where sets of commits graduate to a more stable silo when they’re fully tested.

You can keep doing this for several levels of stability. Some larger projects also have a proposed or pu (proposed updates) branch that has integrated branches that may not be ready to go into the next or master branch. The idea is that your branches are at various levels of stability; when they reach a more stable level, they’re merged into the branch above them. Again, having multiple long-running branches isn’t necessary, but it’s often helpful, especially when you’re dealing with very large or complex projects.

Topic branches, however, are useful in projects of any size. A topic branch is a short-lived branch that you create and use for a single particular feature or related work. This is something you’ve likely never done with a VCS before because it’s generally too expensive to create and merge branches. But in Git it’s common to create, work on, merge, and delete branches several times a day.

You saw this in the last section with the iss53 and hotfix branches you created. You did a few commits on them and deleted them directly after merging them into your main branch. This technique allows you to context-switch quickly and completely – because your work is separated into silos where all the changes in that branch have to do with that topic, it’s easier to see what has happened during code review and such. You can keep the changes there for minutes, days, or months, and merge them in when they’re ready, regardless of the order in which they were created or worked on.

Consider an example of doing some work (on master), branching off for an issue (iss91), working on it for a bit, branching off the second branch to try another way of handling the same thing (iss91v2), going back to your master branch and working there for a while, and then branching off there to do some work that you’re not sure is a good idea (dumbidea branch). Your commit history will look something like this:

Now, let’s say you decide you like the second solution to your issue best (iss91v2); and you showed the dumbidea branch to your coworkers, and it turns out to be genius. You can throw away the original iss91 branch (losing commits C5 and C6) and merge in the other two. Your history then looks like this:

We will go into more detail about the various possible workflows for your Git project in 分散式的 Git, so before you decide which branching scheme your next project will use, be sure to read that chapter.

It’s important to remember when you’re doing all this that these branches are completely local. When you’re branching and merging, everything is being done only in your Git repository – no server communication is happening.

When you want to share a branch with the world, you need to push it up to a remote that you have write access to. Your local branches aren’t automatically synchronized to the remotes you write to – you have to explicitly push the branches you want to share. That way, you can use private branches for work you don’t want to share, and push up only the topic branches you want to collaborate on.

If you have a branch named serverfix that you want to work on with others, you can push it up the same way you pushed your first branch. Run git push <remote> <branch>:

This is a bit of a shortcut. Git automatically expands the serverfix branchname out to refs/heads/serverfix:refs/heads/serverfix, which means, “Take my serverfix local branch and push it to update the remote’s serverfix branch.” We’ll go over the refs/heads/ part in detail in Git Internals, but you can generally leave it off. You can also do git push origin serverfix:serverfix, which does the same thing – it says, “Take my serverfix and make it the remote’s serverfix.” You can use this format to push a local branch into a remote branch that is named differently. If you didn’t want it to be called serverfix on the remote, you could instead run git push origin serverfix:awesomebranch to push your local serverfix branch to the awesomebranch branch on the remote project.

The next time one of your collaborators fetches from the server, they will get a reference to where the server’s version of serverfix is under the remote branch origin/serverfix:

It’s important to note that when you do a fetch that brings down new remote-tracking branches, you don’t automatically have local, editable copies of them. In other words, in this case, you don’t have a new serverfix branch – you only have an origin/serverfix pointer that you can’t modify.

To merge this work into your current working branch, you can run git merge origin/serverfix. If you want your own serverfix branch that you can work on, you can base it off your remote-tracking branch:

This gives you a local branch that you can work on that starts where origin/serverfix is.

Checking out a local branch from a remote-tracking branch automatically creates what is called a “tracking branch” (and the branch it tracks is called an “upstream branch”). Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type git pull, Git automatically knows which server to fetch from and branch to merge into.

When you clone a repository, it generally automatically creates a master branch that tracks origin/master. However, you can set up other tracking branches if you wish – ones that track branches on other remotes, or don’t track the master branch. The simple case is the example you just saw, running git checkout -b [branch] [remotename]/[branch]. This is a common enough operation that git provides the --track shorthand:

In fact, this is so common that there’s even a shortcut for that shortcut. If the branch name you’re trying to checkout (a) doesn’t exist and (b) exactly matches a name on only one remote, Git will create a tracking branch for you:

To set up a local branch with a different name than the remote branch, you can easily use the first version with a different local branch name:

Now, your local branch sf will automatically pull from origin/serverfix.

If you already have a local branch and want to set it to a remote branch you just pulled down, or want to change the upstream branch you’re tracking, you can use the -u or --set-upstream-to option to git branch to explicitly set it at any time.

If you want to see what tracking branches you have set up, you can use the -vv option to git branch. This will list out your local branches with more information including what each branch is tracking and if your local branch is ahead, behind or both.

So here we can see that our iss53 branch is tracking origin/iss53 and is “ahead” by two, meaning that we have two commits locally that are not pushed to the server. We can also see that our master branch is tracking origin/master and is up to date. Next we can see that our serverfix branch is tracking the server-fix-good branch on our teamone server and is ahead by three and behind by one, meaning that there is one commit on the server we haven’t merged in yet and three commits locally that we haven’t pushed. Finally we can see that our testing branch is not tracking any remote branch.

It’s important to note that these numbers are only since the last time you fetched from each server. This command does not reach out to the servers, it’s telling you about what it has cached from these servers locally. If you want totally up to date ahead and behind numbers, you’ll need to fetch from all your remotes right before running this. You could do that like this: git fetch --all; git branch -vv

While the git fetch command will fetch down all the changes on the server that you don’t have yet, it will not modify your working directory at all. It will simply get the data for you and let you merge it yourself. However, there is a command called git pull which is essentially a git fetch immediately followed by a git merge in most cases. If you have a tracking branch set up as demonstrated in the last section, either by explicitly setting it or by having it created for you by the clone or checkout commands, git pull will look up what server and branch your current branch is tracking, fetch from that server and then try to merge in that remote branch.

Generally it’s better to simply use the fetch and merge commands explicitly as the magic of git pull can often be confusing.

Suppose you’re done with a remote branch – say you and your collaborators are finished with a feature and have merged it into your remote’s master branch (or whatever branch your stable codeline is in). You can delete a remote branch using the --delete option to git push. If you want to delete your serverfix branch from the server, you run the following:

Basically all this does is remove the pointer from the server. The Git server will generally keep the data there for a while until a garbage collection runs, so if it was accidentally deleted, it’s often easy to recover.

If you go back to an earlier example from 合併的基本用法, you can see that you diverged your work and made commits on two different branches.

The easiest way to integrate the branches, as we’ve already covered, is the merge command. It performs a three-way merge between the two latest branch snapshots (C3 and C4) and the most recent common ancestor of the two (C2), creating a new snapshot (and commit).

However, there is another way: you can take the patch of the change that was introduced in C4 and reapply it on top of C3. In Git, this is called rebasing. With the rebase command, you can take all the changes that were committed on one branch and replay them on another one.

In this example, you’d run the following:

It works by going to the common ancestor of the two branches (the one you’re on and the one you’re rebasing onto), getting the diff introduced by each commit of the branch you’re on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn.

At this point, you can go back to the master branch and do a fast-forward merge.

Now, the snapshot pointed to by C4' is exactly the same as the one that was pointed to by C5 in the merge example. There is no difference in the end product of the integration, but rebasing makes for a cleaner history. If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel.

Often, you’ll do this to make sure your commits apply cleanly on a remote branch – perhaps in a project to which you’re trying to contribute but that you don’t maintain. In this case, you’d do your work in a branch and then rebase your work onto origin/master when you were ready to submit your patches to the main project. That way, the maintainer doesn’t have to do any integration work – just a fast-forward or a clean apply.

Note that the snapshot pointed to by the final commit you end up with, whether it’s the last of the rebased commits for a rebase or the final merge commit after a merge, is the same snapshot – it’s only the history that is different. Rebasing replays changes from one line of work onto another in the order they were introduced, whereas merging takes the endpoints and merges them together.

You can also have your rebase replay on something other than the rebase target branch. Take a history like A history with a topic branch off another topic branch, for example. You branched a topic branch (server) to add some server-side functionality to your project, and made a commit. Then, you branched off that to make the client-side changes (client) and committed a few times. Finally, you went back to your server branch and did a few more commits.

Suppose you decide that you want to merge your client-side changes into your mainline for a release, but you want to hold off on the server-side changes until it’s tested further. You can take the changes on client that aren’t on server (C8 and C9) and replay them on your master branch by using the --onto option of git rebase:

This basically says, “Check out the client branch, figure out the patches from the common ancestor of the client and server branches, and then replay them onto master.” It’s a bit complex, but the result is pretty cool.

Now you can fast-forward your master branch (see Fast-forwarding your master branch to include the client branch changes):

Let’s say you decide to pull in your server branch as well. You can rebase the server branch onto the master branch without having to check it out first by running git rebase [basebranch] [topicbranch] – which checks out the topic branch (in this case, server) for you and replays it onto the base branch (master):

This replays your server work on top of your master work, as shown in Rebasing your server branch on top of your master branch.

Then, you can fast-forward the base branch (master):

You can remove the client and server branches because all the work is integrated and you don’t need them anymore, leaving your history for this entire process looking like Final commit history:

Ahh, but the bliss of rebasing isn’t without its drawbacks, which can be summed up in a single line:

Do not rebase commits that exist outside your repository.

If you follow that guideline, you’ll be fine. If you don’t, people will hate you, and you’ll be scorned by friends and family.

When you rebase stuff, you’re abandoning existing commits and creating new ones that are similar but different. If you push commits somewhere and others pull them down and base work on them, and then you rewrite those commits with git rebase and push them up again, your collaborators will have to re-merge their work and things will get messy when you try to pull their work back into yours.

Let’s look at an example of how rebasing work that you’ve made public can cause problems. Suppose you clone from a central server and then do some work off that. Your commit history looks like this:

Now, someone else does more work that includes a merge, and pushes that work to the central server. You fetch it and merge the new remote branch into your work, making your history look something like this:

Next, the person who pushed the merged work decides to go back and rebase their work instead; they do a git push --force to overwrite the history on the server. You then fetch from that server, bringing down the new commits.

Now you’re both in a pickle. If you do a git pull, you’ll create a merge commit which includes both lines of history, and your repository will look like this:

If you run a git log when your history looks like this, you’ll see two commits that have the same author, date, and message, which will be confusing. Furthermore, if you push this history back up to the server, you’ll reintroduce all those rebased commits to the central server, which can further confuse people. It’s pretty safe to assume that the other developer doesn’t want C4 and C6 to be in the history; that’s why they rebased in the first place.

If you do find yourself in a situation like this, Git has some further magic that might help you out. If someone on your team force pushes changes that overwrite work that you’ve based work on, your challenge is to figure out what is yours and what they’ve rewritten.

It turns out that in addition to the commit SHA-1 checksum, Git also calculates a checksum that is based just on the patch introduced with the commit. This is called a “patch-id”.

If you pull down work that was rewritten and rebase it on top of the new commits from your partner, Git can often successfully figure out what is uniquely yours and apply them back on top of the new branch.

For instance, in the previous scenario, if instead of doing a merge when we’re at Someone pushes rebased commits, abandoning commits you’ve based your work on we run git rebase teamone/master, Git will:

So instead of the result we see in You merge in the same work again into a new merge commit, we would end up with something more like Rebase on top of force-pushed rebase work..

This only works if C4 and C4' that your partner made are almost exactly the same patch. Otherwise the rebase won’t be able to tell that it’s a duplicate and will add another C4-like patch (which will probably fail to apply cleanly, since the changes would already be at least somewhat there).

You can also simplify this by running a git pull --rebase instead of a normal git pull. Or you could do it manually with a git fetch followed by a git rebase teamone/master in this case.

If you are using git pull and want to make --rebase the default, you can set the pull.rebase config value with something like git config --global pull.rebase true.

If you treat rebasing as a way to clean up and work with commits before you push them, and if you only rebase commits that have never been available publicly, then you’ll be fine. If you rebase commits that have already been pushed publicly, and people may have based work on those commits, then you may be in for some frustrating trouble, and the scorn of your teammates.

If you or a partner does find it necessary at some point, make sure everyone knows to run git pull --rebase to try to make the pain after it happens a little bit simpler.

Now that you’ve seen rebasing and merging in action, you may be wondering which one is better. Before we can answer this, let’s step back a bit and talk about what history means.

One point of view on this is that your repository’s commit history is a record of what actually happened. It’s a historical document, valuable in its own right, and shouldn’t be tampered with. From this angle, changing the commit history is almost blasphemous; you’re lying about what actually transpired. So what if there was a messy series of merge commits? That’s how it happened, and the repository should preserve that for posterity.

The opposing point of view is that the commit history is the story of how your project was made. You wouldn’t publish the first draft of a book, and the manual for how to maintain your software deserves careful editing. This is the camp that uses tools like rebase and filter-branch to tell the story in the way that’s best for future readers.

Now, to the question of whether merging or rebasing is better: hopefully you’ll see that it’s not that simple. Git is a powerful tool, and allows you to do many things to and with your history, but every team and every project is different. Now that you know how both of these things work, it’s up to you to decide which one is best for your particular situation.

In general the way to get the best of both worlds is to rebase local changes you’ve made but haven’t shared yet before you push them in order to clean up your story, but never rebase anything you’ve pushed somewhere.

The most basic is the Local protocol, in which the remote repository is in another directory on disk. This is often used if everyone on your team has access to a shared filesystem such as an NFS mount, or in the less likely case that everyone logs in to the same computer. The latter wouldn’t be ideal, because all your code repository instances would reside on the same computer, making a catastrophic loss much more likely.

If you have a shared mounted filesystem, then you can clone, push to, and pull from a local file-based repository. To clone a repository like this or to add one as a remote to an existing project, use the path to the repository as the URL. For example, to clone a local repository, you can run something like this:

Or you can do this:

Git operates slightly differently if you explicitly specify file:// at the beginning of the URL. If you just specify the path, Git tries to use hardlinks or directly copy the files it needs. If you specify file://, Git fires up the processes that it normally uses to transfer data over a network which is generally a lot less efficient method of transferring the data. The main reason to specify the file:// prefix is if you want a clean copy of the repository with extraneous references or objects left out – generally after an import from another version-control system or something similar (see Git Internals for maintenance tasks). We’ll use the normal path here because doing so is almost always faster.

To add a local repository to an existing Git project, you can run something like this:

Then, you can push to and pull from that remote as though you were doing so over a network.

Git can communicate over HTTP in two different modes. Prior to Git 1.6.6 there was only one way it could do this which was very simple and generally read-only. In version 1.6.6 a new, smarter protocol was introduced that involved Git being able to intelligently negotiate data transfer in a manner similar to how it does over SSH. In the last few years, this new HTTP protocol has become very popular since it’s simpler for the user and smarter about how it communicates. The newer version is often referred to as the “Smart” HTTP protocol and the older way as “Dumb” HTTP. We’ll cover the newer “smart” HTTP protocol first.

A common transport protocol for Git when self-hosting is over SSH. This is because SSH access to servers is already set up in most places – and if it isn’t, it’s easy to do. SSH is also an authenticated network protocol; and because it’s ubiquitous, it’s generally easy to set up and use.

To clone a Git repository over SSH, you can specify ssh:// URL like this:

Or you can use the shorter scp-like syntax for the SSH protocol:

You can also not specify a user, and Git assumes the user you’re currently logged in as.

Next is the Git protocol. This is a special daemon that comes packaged with Git; it listens on a dedicated port (9418) that provides a service similar to the SSH protocol, but with absolutely no authentication. In order for a repository to be served over the Git protocol, you must create the git-daemon-export-ok file – the daemon won’t serve a repository without that file in it – but other than that there is no security. Either the Git repository is available for everyone to clone or it isn’t. This means that there is generally no pushing over this protocol. You can enable push access; but given the lack of authentication, if you turn on push access, anyone on the internet who finds your project’s URL could push to your project. Suffice it to say that this is rare.

Now that you have a bare copy of your repository, all you need to do is put it on a server and set up your protocols. Let’s say you’ve set up a server called git.example.com that you have SSH access to, and you want to store all your Git repositories under the /srv/git directory. Assuming that /srv/git exists on that server, you can set up your new repository by copying your bare repository over:

At this point, other users who have SSH access to the same server which has read-access to the /srv/git directory can clone your repository by running

If a user SSHs into a server and has write access to the /srv/git/my_project.git directory, they will also automatically have push access.

Git will automatically add group write permissions to a repository properly if you run the git init command with the --shared option.

You see how easy it is to take a Git repository, create a bare version, and place it on a server to which you and your collaborators have SSH access. Now you’re ready to collaborate on the same project.

It’s important to note that this is literally all you need to do to run a useful Git server to which several people have access – just add SSH-able accounts on a server, and stick a bare repository somewhere that all those users have read and write access to. You’re ready to go – nothing else needed.

In the next few sections, you’ll see how to expand to more sophisticated setups. This discussion will include not having to create user accounts for each user, adding public read access to repositories, setting up web UIs and more. However, keep in mind that to collaborate with a couple of people on a private project, all you need is an SSH server and a bare repository.

If you’re a small outfit or are just trying out Git in your organization and have only a few developers, things can be simple for you. One of the most complicated aspects of setting up a Git server is user management. If you want some repositories to be read-only to certain users and read/write to others, access and permissions can be a bit more difficult to arrange.

GitLab is a database-backed web application, so its installation is a bit more involved than some other git servers. Fortunately, this process is very well-documented and supported.

There are a few methods you can pursue to install GitLab. To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab, and tweak the configuration to match your particular environment. One nice touch Bitnami has included is the login screen (accessed by typing alt-→); it tells you the IP address and default username and password for the installed GitLab.

For anything else, follow the guidance in the GitLab Community Edition readme, which can be found at https://gitlab.com/gitlab-org/gitlab-ce/tree/master. There you’ll find assistance for installing GitLab using Chef recipes, a virtual machine on Digital Ocean, and RPM and DEB packages (which, as of this writing, are in beta). There’s also “unofficial” guidance on getting GitLab running with non-standard operating systems and databases, a fully-manual installation script, and many other topics.

GitLab’s administration interface is accessed over the web. Simply point your browser to the hostname or IP address where GitLab is installed, and log in as an admin user. The default username is admin@local.host, and the default password is 5iveL!fe (which you will be prompted to change as soon as you enter it). Once logged in, click the “Admin area” icon in the menu at the top right.

The first thing you’ll want to do with GitLab is create a new project. This is accomplished by clicking the “+” icon on the toolbar. You’ll be asked for the project’s name, which namespace it should belong to, and what its visibility level should be. Most of what you specify here isn’t permanent, and can be re-adjusted later through the settings interface. Click “Create Project”, and you’re done.

Once the project exists, you’ll probably want to connect it with a local Git repository. Each project is accessible over HTTPS or SSH, either of which can be used to configure a Git remote. The URLs are visible at the top of the project’s home page. For an existing local repository, this command will create a remote named gitlab to the hosted location:

If you don’t have a local copy of the repository, you can simply do this:

The web UI provides access to several useful views of the repository itself. Each project’s home page shows recent activity, and links along the top will lead you to views of the project’s files and commit log.

The simplest way of working together on a GitLab project is by giving another user direct push access to the git repository. You can add a user to a project by going to the “Members” section of that project’s settings, and associating the new user with an access level (the different access levels are discussed a bit in 群組). By giving a user an access level of “Developer” or above, that user can push commits and branches directly to the repository with impunity.

Another, more decoupled way of collaboration is by using merge requests. This feature enables any user that can see a project to contribute to it in a controlled way. Users with direct access can simply create a branch, push commits to it, and open a merge request from their branch back into master or any other branch. Users who don’t have push permissions for a repository can “fork” it (create their own copy), push commits to that copy, and open a merge request from their fork back to the main project. This model allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users.

Merge requests and issues are the main units of long-lived discussion in GitLab. Each merge request allows a line-by-line discussion of the proposed change (which supports a lightweight kind of code review), as well as a general overall discussion thread. Both can be assigned to users, or organized into milestones.

This section is focused mainly on the Git-related features of GitLab, but as a mature project, it provides many other features to help your team work together, such as project wikis and system maintenance tools. One benefit to GitLab is that, once the server is set up and running, you’ll rarely need to tweak a configuration file or access the server via SSH; most administration and general usage can be accomplished through the in-browser interface.

In centralized systems, there is generally a single collaboration model–the centralized workflow. One central hub, or repository, can accept code, and everyone synchronizes their work to it. A number of developers are nodes – consumers of that hub – and synchronize to that one place.

This means that if two developers clone from the hub and both make changes, the first developer to push their changes back up can do so with no problems. The second developer must merge in the first one’s work before pushing changes up, so as not to overwrite the first developer’s changes. This concept is as true in Git as it is in Subversion (or any CVCS), and this model works perfectly well in Git.

If you are already comfortable with a centralized workflow in your company or team, you can easily continue using that workflow with Git. Simply set up a single repository, and give everyone on your team push access; Git won’t let users overwrite each other. Say John and Jessica both start working at the same time. John finishes his change and pushes it to the server. Then Jessica tries to push her changes, but the server rejects them. She is told that she’s trying to push non-fast-forward changes and that she won’t be able to do so until she fetches and merges. This workflow is attractive to a lot of people because it’s a paradigm that many are familiar and comfortable with.

This is also not limited to small teams. With Git’s branching model, it’s possible for hundreds of developers to successfully work on a single project through dozens of branches simultaneously.

Because Git allows you to have multiple remote repositories, it’s possible to have a workflow where each developer has write access to their own public repository and read access to everyone else’s. This scenario often includes a canonical repository that represents the “official” project. To contribute to that project, you create your own public clone of the project and push your changes to it. Then, you can send a request to the maintainer of the main project to pull in your changes. The maintainer can then add your repository as a remote, test your changes locally, merge them into their branch, and push back to their repository. The process works as follows (see Integration-manager workflow.):

This is a very common workflow with hub-based tools like GitHub or GitLab, where it’s easy to fork a project and push your changes into your fork for everyone to see. One of the main advantages of this approach is that you can continue to work, and the maintainer of the main repository can pull in your changes at any time. Contributors don’t have to wait for the project to incorporate their changes – each party can work at their own pace.

This is a variant of a multiple-repository workflow. It’s generally used by huge projects with hundreds of collaborators; one famous example is the Linux kernel. Various integration managers are in charge of certain parts of the repository; they’re called lieutenants. All the lieutenants have one integration manager known as the benevolent dictator. The benevolent dictator’s repository serves as the reference repository from which all the collaborators need to pull. The process works like this (see Benevolent dictator workflow.):

This kind of workflow isn’t common, but can be useful in very big projects, or in highly hierarchical environments. It allows the project leader (the dictator) to delegate much of the work and collect large subsets of code at multiple points before integrating them.

These are some commonly used workflows that are possible with a distributed system like Git, but you can see that many variations are possible to suit your particular real-world workflow. Now that you can (hopefully) determine which workflow combination may work for you, we’ll cover some more specific examples of how to accomplish the main roles that make up the different flows. In the next section, you’ll learn about a few common patterns for contributing to a project.

Before we start looking at the specific use cases, here’s a quick note about commit messages. Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier. The Git project provides a document that lays out a number of good tips for creating commits from which to submit patches – you can read it in the Git source code in the Documentation/SubmittingPatches file.

First, you don’t want to submit any whitespace errors. Git provides an easy way to check for this – before you commit, run git diff --check, which identifies possible whitespace errors and lists them for you.

If you run that command before committing, you can tell if you’re about to commit whitespace issues that may annoy other developers.

Next, try to make each commit a logically separate changeset. If you can, try to make your changes digestible – don’t code for a whole weekend on five different issues and then submit them all as one massive commit on Monday. Even if you don’t commit during the weekend, use the staging area on Monday to split your work into at least one commit per issue, with a useful message per commit. If some of the changes modify the same file, try to use git add --patch to partially stage files (covered in detail in Interactive Staging). The project snapshot at the tip of the branch is identical whether you do one commit or five, as long as all the changes are added at some point, so try to make things easier on your fellow developers when they have to review your changes. This approach also makes it easier to pull out or revert one of the changesets if you need to later. Rewriting History describes a number of useful Git tricks for rewriting history and interactively staging files – use these tools to help craft a clean and understandable history before sending the work to someone else.

The last thing to keep in mind is the commit message. Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation. The Git project requires that the more detailed explanation include your motivation for the change and contrast its implementation with previous behavior – this is a good guideline to follow. It’s also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of “I added tests for” or “Adding tests for,” use “Add tests for.” Here is a template originally written by Tim Pope:

If all your commit messages look like this, things will be a lot easier for you and the developers you work with. The Git project has well-formatted commit messages – try running git log --no-merges there to see what a nicely formatted project-commit history looks like.

In the following examples, and throughout most of this book, for the sake of brevity this book doesn’t have nicely-formatted messages like this; instead, we use the -m option to git commit. Do as we say, not as we do.

The simplest setup you’re likely to encounter is a private project with one or two other developers. “Private,” in this context, means closed-source – not accessible to the outside world. You and the other developers all have push access to the repository.

In this environment, you can follow a workflow similar to what you might do when using Subversion or another centralized system. You still get the advantages of things like offline committing and vastly simpler branching and merging, but the workflow can be very similar; the main difference is that merges happen client-side rather than on the server at commit time. Let’s see what it might look like when two developers start to work together with a shared repository. The first developer, John, clones the repository, makes a change, and commits locally. (The protocol messages have been replaced with ... in these examples to shorten them somewhat.)

The second developer, Jessica, does the same thing – clones the repository and commits a change:

Now, Jessica pushes her work up to the server:

John tries to push his change up, too:

John isn’t allowed to push because Jessica has pushed in the meantime. This is especially important to understand if you’re used to Subversion, because you’ll notice that the two developers didn’t edit the same file. Although Subversion automatically does such a merge on the server if different files are edited, in Git you must merge the commits locally. John has to fetch Jessica’s changes and merge them in before he will be allowed to push:

At this point, John’s local repository looks something like this:

John has a reference to the changes Jessica pushed up, but he has to merge them into his own work before he is allowed to push:

The merge goes smoothly – John’s commit history now looks like this:

Now, John can test his code to make sure it still works properly, and then he can push his new merged work up to the server:

Finally, John’s commit history looks like this:

In the meantime, Jessica has been working on a topic branch. She’s created a topic branch called issue54 and done three commits on that branch. She hasn’t fetched John’s changes yet, so her commit history looks like this:

Jessica wants to sync up with John, so she fetches:

That pulls down the work John has pushed up in the meantime. Jessica’s history now looks like this:

Jessica thinks her topic branch is ready, but she wants to know what she has to merge into her work so that she can push. She runs git log to find out:

The issue54..origin/master syntax is a log filter that asks Git to only show the list of commits that are on the latter branch (in this case origin/master) that are not on the first branch (in this case issue54). We’ll go over this syntax in detail in Commit Ranges.

For now, we can see from the output that there is a single commit that John has made that Jessica has not merged in. If she merges origin/master, that is the single commit that will modify her local work.

Now, Jessica can merge her topic work into her master branch, merge John’s work (origin/master) into her master branch, and then push back to the server again. First, she switches back to her master branch to integrate all this work:

She can merge either origin/master or issue54 first – they’re both upstream, so the order doesn’t matter. The end snapshot should be identical no matter which order she chooses; only the history will be slightly different. She chooses to merge in issue54 first:

No problems occur; as you can see it was a simple fast-forward. Now Jessica merges in John’s work (origin/master):

Everything merges cleanly, and Jessica’s history looks like this:

Now origin/master is reachable from Jessica’s master branch, so she should be able to successfully push (assuming John hasn’t pushed again in the meantime):

Each developer has committed a few times and merged each other’s work successfully.

That is one of the simplest workflows. You work for a while, generally in a topic branch, and merge into your master branch when it’s ready to be integrated. When you want to share that work, you fetch and merge your master from origin/master if it has changed, and finally push to the master branch on the server. The general sequence is something like this:

In this next scenario, you’ll look at contributor roles in a larger private group. You’ll learn how to work in an environment where small groups collaborate on features and then those team-based contributions are integrated by another party.

Let’s say that John and Jessica are working together on one feature, while Jessica and Josie are working on a second. In this case, the company is using a type of integration-manager workflow where the work of the individual groups is integrated only by certain engineers, and the master branch of the main repo can be updated only by those engineers. In this scenario, all work is done in team-based branches and pulled together by the integrators later.

Let’s follow Jessica’s workflow as she works on her two features, collaborating in parallel with two different developers in this environment. Assuming she already has her repository cloned, she decides to work on featureA first. She creates a new branch for the feature and does some work on it there:

At this point, she needs to share her work with John, so she pushes her featureA branch commits up to the server. Jessica doesn’t have push access to the master branch – only the integrators do – so she has to push to another branch in order to collaborate with John:

Jessica emails John to tell him that she’s pushed some work into a branch named featureA and he can look at it now. While she waits for feedback from John, Jessica decides to start working on featureB with Josie. To begin, she starts a new feature branch, basing it off the server’s master branch:

Now, Jessica makes a couple of commits on the featureB branch:

Jessica’s repository looks like this:

She’s ready to push up her work, but gets an email from Josie that a branch with some initial work on it was already pushed to the server as featureBee. Jessica first needs to merge those changes in with her own before she can push to the server. She can then fetch Josie’s changes down with git fetch:

Jessica can now merge this into the work she did with git merge:

There is a bit of a problem – she needs to push the merged work in her featureB branch to the featureBee branch on the server. She can do so by specifying the local branch followed by a colon (:) followed by the remote branch to the git push command:

This is called a refspec. See The Refspec for a more detailed discussion of Git refspecs and different things you can do with them. Also notice the -u flag; this is short for --set-upstream, which configures the branches for easier pushing and pulling later.

Next, John emails Jessica to say he’s pushed some changes to the featureA branch and asks her to verify them. She runs a git fetch to pull down those changes:

Then, she can see what has been changed with git log:

Finally, she merges John’s work into her own featureA branch:

Jessica wants to tweak something, so she commits again and then pushes this back up to the server:

Jessica’s commit history now looks something like this:

Jessica, Josie, and John inform the integrators that the featureA and featureBee branches on the server are ready for integration into the mainline. After the integrators merge these branches into the mainline, a fetch will bring down the new merge commit, making the history look like this:

Many groups switch to Git because of this ability to have multiple teams working in parallel, merging the different lines of work late in the process. The ability of smaller subgroups of a team to collaborate via remote branches without necessarily having to involve or impede the entire team is a huge benefit of Git. The sequence for the workflow you saw here is something like this:

Contributing to public projects is a bit different. Because you don’t have the permissions to directly update branches on the project, you have to get the work to the maintainers some other way. This first example describes contributing via forking on Git hosts that support easy forking. Many hosting sites support this (including GitHub, BitBucket, Google Code, repo.or.cz, and others), and many project maintainers expect this style of contribution. The next section deals with projects that prefer to accept contributed patches via email.

First, you’ll probably want to clone the main repository, create a topic branch for the patch or patch series you’re planning to contribute, and do your work there. The sequence looks basically like this:

When your branch work is finished and you’re ready to contribute it back to the maintainers, go to the original project page and click the “Fork” button, creating your own writable fork of the project. You then need to add in this new repository URL as a second remote, in this case named myfork:

Then you need to push your work up to it. It’s easiest to push the topic branch you’re working on up to your repository, rather than merging into your master branch and pushing that up. The reason is that if the work isn’t accepted or is cherry picked, you don’t have to rewind your master branch. If the maintainers merge, rebase, or cherry-pick your work, you’ll eventually get it back via pulling from their repository anyhow:

When your work has been pushed up to your fork, you need to notify the maintainer. This is often called a pull request, and you can either generate it via the website – GitHub has its own Pull Request mechanism that we’ll go over in GitHub – or you can run the git request-pull command and email the output to the project maintainer manually.

The request-pull command takes the base branch into which you want your topic branch pulled and the Git repository URL you want them to pull from, and outputs a summary of all the changes you’re asking to be pulled in. For instance, if Jessica wants to send John a pull request, and she’s done two commits on the topic branch she just pushed up, she can run this:

The output can be sent to the maintainer – it tells them where the work was branched from, summarizes the commits, and tells where to pull this work from.

On a project for which you’re not the maintainer, it’s generally easier to have a branch like master always track origin/master and to do your work in topic branches that you can easily discard if they’re rejected. Having work themes isolated into topic branches also makes it easier for you to rebase your work if the tip of the main repository has moved in the meantime and your commits no longer apply cleanly. For example, if you want to submit a second topic of work to the project, don’t continue working on the topic branch you just pushed up – start over from the main repository’s master branch:

Now, each of your topics is contained within a silo – similar to a patch queue – that you can rewrite, rebase, and modify without the topics interfering or interdepending on each other, like so:

Let’s say the project maintainer has pulled in a bunch of other patches and tried your first branch, but it no longer cleanly merges. In this case, you can try to rebase that branch on top of origin/master, resolve the conflicts for the maintainer, and then resubmit your changes:

This rewrites your history to now look like Commit history after featureA work..

Because you rebased the branch, you have to specify the -f to your push command in order to be able to replace the featureA branch on the server with a commit that isn’t a descendant of it. An alternative would be to push this new work to a different branch on the server (perhaps called featureAv2).

Let’s look at one more possible scenario: the maintainer has looked at work in your second branch and likes the concept but would like you to change an implementation detail. You’ll also take this opportunity to move the work to be based off the project’s current master branch. You start a new branch based off the current origin/master branch, squash the featureB changes there, resolve any conflicts, make the implementation change, and then push that up as a new branch:

The --squash option takes all the work on the merged branch and squashes it into one changeset producing the repository state as if a real merge happened, without actually making a merge commit. This means your future commit will have one parent only and allows you to introduce all the changes from another branch and then make more changes before recording the new commit. Also the --no-commit option can be useful to delay the merge commit in case of the default merge process.

Now you can send the maintainer a message that you’ve made the requested changes and they can find those changes in your featureBv2 branch.

Many projects have established procedures for accepting patches – you’ll need to check the specific rules for each project, because they will differ. Since there are several older, larger projects which accept patches via a developer mailing list, we’ll go over an example of that now.

The workflow is similar to the previous use case – you create topic branches for each patch series you work on. The difference is how you submit them to the project. Instead of forking the project and pushing to your own writable version, you generate email versions of each commit series and email them to the developer mailing list:

Now you have two commits that you want to send to the mailing list. You use git format-patch to generate the mbox-formatted files that you can email to the list – it turns each commit into an email message with the first line of the commit message as the subject and the rest of the message plus the patch that the commit introduces as the body. The nice thing about this is that applying a patch from an email generated with format-patch preserves all the commit information properly.

The format-patch command prints out the names of the patch files it creates. The -M switch tells Git to look for renames. The files end up looking like this:

You can also edit these patch files to add more information for the email list that you don’t want to show up in the commit message. If you add text between the --- line and the beginning of the patch (the diff --git line), then developers can read it; but applying the patch excludes it.

To email this to a mailing list, you can either paste the file into your email program or send it via a command-line program. Pasting the text often causes formatting issues, especially with “smarter” clients that don’t preserve newlines and other whitespace appropriately. Luckily, Git provides a tool to help you send properly formatted patches via IMAP, which may be easier for you. We’ll demonstrate how to send a patch via Gmail, which happens to be the email agent we know best; you can read detailed instructions for a number of mail programs at the end of the aforementioned Documentation/SubmittingPatches file in the Git source code.

First, you need to set up the imap section in your ~/.gitconfig file. You can set each value separately with a series of git config commands, or you can add them manually, but in the end your config file should look something like this:

If your IMAP server doesn’t use SSL, the last two lines probably aren’t necessary, and the host value will be imap:// instead of imaps://. When that is set up, you can use git imap-send to place the patch series in the Drafts folder of the specified IMAP server:

At this point, you should be able to go to your Drafts folder, change the To field to the mailing list you’re sending the patch to, possibly CC the maintainer or person responsible for that section, and send it off.

You can also send the patches through an SMTP server. As before, you can set each value separately with a series of git config commands, or you can add them manually in the sendemail section in your ~/.gitconfig file:

After this is done, you can use git send-email to send your patches:

Then, Git spits out a bunch of log information looking something like this for each patch you’re sending:

This section has covered a number of common workflows for dealing with several very different types of Git projects you’re likely to encounter, and introduced a couple of new tools to help you manage this process. Next, you’ll see how to work the other side of the coin: maintaining a Git project. You’ll learn how to be a benevolent dictator or integration manager.

When you’re thinking of integrating new work, it’s generally a good idea to try it out in a topic branch – a temporary branch specifically made to try out that new work. This way, it’s easy to tweak a patch individually and leave it if it’s not working until you have time to come back to it. If you create a simple branch name based on the theme of the work you’re going to try, such as ruby_client or something similarly descriptive, you can easily remember it if you have to abandon it for a while and come back later. The maintainer of the Git project tends to namespace these branches as well – such as sc/ruby_client, where sc is short for the person who contributed the work. As you’ll remember, you can create the branch based off your master branch like this:

Or, if you want to also switch to it immediately, you can use the checkout -b option:

Now you’re ready to add your contributed work into this topic branch and determine if you want to merge it into your longer-term branches.

If you receive a patch over email that you need to integrate into your project, you need to apply the patch in your topic branch to evaluate it. There are two ways to apply an emailed patch: with git apply or with git am.

If your contribution came from a Git user who set up their own repository, pushed a number of changes into it, and then sent you the URL to the repository and the name of the remote branch the changes are in, you can add them as a remote and do merges locally.

For instance, if Jessica sends you an email saying that she has a great new feature in the ruby-client branch of her repository, you can test it by adding the remote and checking out that branch locally:

If she emails you again later with another branch containing another great feature, you can fetch and check out because you already have the remote setup.

This is most useful if you’re working with a person consistently. If someone only has a single patch to contribute once in a while, then accepting it over email may be less time consuming than requiring everyone to run their own server and having to continually add and remove remotes to get a few patches. You’re also unlikely to want to have hundreds of remotes, each for someone who contributes only a patch or two. However, scripts and hosted services may make this easier – it depends largely on how you develop and how your contributors develop.

The other advantage of this approach is that you get the history of the commits as well. Although you may have legitimate merge issues, you know where in your history their work is based; a proper three-way merge is the default rather than having to supply a -3 and hope the patch was generated off a public commit to which you have access.

If you aren’t working with a person consistently but still want to pull from them in this way, you can provide the URL of the remote repository to the git pull command. This does a one-time pull and doesn’t save the URL as a remote reference:

Now you have a topic branch that contains contributed work. At this point, you can determine what you’d like to do with it. This section revisits a couple of commands so you can see how you can use them to review exactly what you’ll be introducing if you merge this into your main branch.

It’s often helpful to get a review of all the commits that are in this branch but that aren’t in your master branch. You can exclude commits in the master branch by adding the --not option before the branch name. This does the same thing as the master..contrib format that we used earlier. For example, if your contributor sends you two patches and you create a branch called contrib and applied those patches there, you can run this:

To see what changes each commit introduces, remember that you can pass the -p option to git log and it will append the diff introduced to each commit.

To see a full diff of what would happen if you were to merge this topic branch with another branch, you may have to use a weird trick to get the correct results. You may think to run this:

This command gives you a diff, but it may be misleading. If your master branch has moved forward since you created the topic branch from it, then you’ll get seemingly strange results. This happens because Git directly compares the snapshots of the last commit of the topic branch you’re on and the snapshot of the last commit on the master branch. For example, if you’ve added a line in a file on the master branch, a direct comparison of the snapshots will look like the topic branch is going to remove that line.

If master is a direct ancestor of your topic branch, this isn’t a problem; but if the two histories have diverged, the diff will look like you’re adding all the new stuff in your topic branch and removing everything unique to the master branch.

What you really want to see are the changes added to the topic branch – the work you’ll introduce if you merge this branch with master. You do that by having Git compare the last commit on your topic branch with the first common ancestor it has with the master branch.

Technically, you can do that by explicitly figuring out the common ancestor and then running your diff on it:

However, that isn’t convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax. In the context of the diff command, you can put three periods after another branch to do a diff between the last commit of the branch you’re on and its common ancestor with another branch:

This command shows you only the work your current topic branch has introduced since its common ancestor with master. That is a very useful syntax to remember.

When all the work in your topic branch is ready to be integrated into a more mainline branch, the question is how to do it. Furthermore, what overall workflow do you want to use to maintain your project? You have a number of choices, so we’ll cover a few of them.

When you’ve decided to cut a release, you’ll probably want to drop a tag so you can re-create that release at any point going forward. You can create a new tag as discussed in Git 基礎. If you decide to sign the tag as the maintainer, the tagging may look something like this:

If you do sign your tags, you may have the problem of distributing the public PGP key used to sign your tags. The maintainer of the Git project has solved this issue by including their public key as a blob in the repository and then adding a tag that points directly to that content. To do this, you can figure out which key you want by running gpg --list-keys:

Then, you can directly import the key into the Git database by exporting it and piping that through git hash-object, which writes a new blob with those contents into Git and gives you back the SHA-1 of the blob:

Now that you have the contents of your key in Git, you can create a tag that points directly to it by specifying the new SHA-1 value that the hash-object command gave you:

If you run git push --tags, the maintainer-pgp-pub tag will be shared with everyone. If anyone wants to verify a tag, they can directly import your PGP key by pulling the blob directly out of the database and importing it into GPG:

They can use that key to verify all your signed tags. Also, if you include instructions in the tag message, running git show <tag> will let you give the end user more specific instructions about tag verification.

Because Git doesn’t have monotonically increasing numbers like v123 or the equivalent to go with each commit, if you want to have a human-readable name to go with a commit, you can run git describe on that commit. Git gives you the name of the nearest tag with the number of commits on top of that tag and a partial SHA-1 value of the commit you’re describing:

This way, you can export a snapshot or build and name it something understandable to people. In fact, if you build Git from source code cloned from the Git repository, git --version gives you something that looks like this. If you’re describing a commit that you have directly tagged, it gives you the tag name.

The git describe command favors annotated tags (tags created with the -a or -s flag), so release tags should be created this way if you’re using git describe, to ensure the commit is named properly when described. You can also use this string as the target of a checkout or show command, although it relies on the abbreviated SHA-1 value at the end, so it may not be valid forever. For instance, the Linux kernel recently jumped from 8 to 10 characters to ensure SHA-1 object uniqueness, so older git describe output names were invalidated.

Now you want to release a build. One of the things you’ll want to do is create an archive of the latest snapshot of your code for those poor souls who don’t use Git. The command to do this is git archive:

If someone opens that tarball, they get the latest snapshot of your project under a project directory. You can also create a zip archive in much the same way, but by passing the --format=zip option to git archive:

You now have a nice tarball and a zip archive of your project release that you can upload to your website or email to people.

It’s time to email your mailing list of people who want to know what’s happening in your project. A nice way of quickly getting a sort of changelog of what has been added to your project since your last release or email is to use the git shortlog command. It summarizes all the commits in the range you give it; for example, the following gives you a summary of all the commits since your last release, if your last release was named v1.0.1:

You get a clean summary of all the commits since v1.0.1, grouped by author, that you can email to your list.

你現在就可以透過 https:// 協定並使用你剛剛設定的帳號及密碼來認證以連接你的 GitHub 倉儲。 但是，如果只是要克隆公開專案，其實你連註冊都不用 － 剛剛建立的帳號是在我們之後要 fork 專案或是推送變更到你複製的倉儲時才會用到。

如果想要使用 SSH 遠端，你必須要去設定一個公鑰。 （如果你沒有公鑰的話請參考 產生你的 SSH 公鑰。） 點擊視窗右上的連結開啟你的帳戶設定頁面:

然後點選左側的「SSH keys」區塊。

點選 "Add an SSH key" 按鈕，之後替你的金鑰命名，複製你的 ~/.ssh/id_rsa.pub（或是任意檔名）公鑰檔的內容並貼在文字區塊內，然後點擊「Add key」。

再來，你可以把那個自動生成的頭像換成你希望的那個圖像。 首先，切換到「profile」分頁（在 SSH keys 的上面那一個），然後點選「Upload new picture」。

我們會拿個 Git 的圖示來用，而且我們會需要剪裁它。

之後你在網站上的任何互動，大家都會看到你的使用者名稱旁有你的頭像。

如果你剛好有在那知名的 Gravatar 上傳過頭像的話 （通常是 Wordpress 的帳戶會有用到），那個頭像會自動被當成預設的頭像，你就不需要執行這個步驟。

GitHub 是用電郵地址把 Git commits 和使用者關聯在一起的。 如果你擁有多個電郵地址，而且你也想要 GitHub 把他們正確的和你關聯在一起，你需要去管理頁面的 Emails 區塊，加入所有你使用的電子郵件。

在 加入電郵地址 這張圖裡面，我們可以看到各種狀態。 第一個地址是已認證而且設定為主要的電郵地址，意味著所有的通知和其他信件都會寄到這個地址。 第二個地址是已認證，所以可以隨時被切換成主要的地址。 最後一個是未認證的，意味著那並不能作為你的主要地址使用。 如果 GitHub 在站上的任意一個 Git 倉儲的 commit 訊息裡發現有對應的電郵地址，它就會被連結到你的使用者。

最後，為了得到額外的安全保障，你應該要設定二階段驗證（或稱作「2FA」）。 二階段驗證是個越來越熱門的驗證技術，能夠在你的密碼被盜取的時候仍能保障你的帳戶的安全。 開啟這個功能後，GitHub 會要求你提供兩個不同的方式來驗證。所以在其中一個失效時，攻擊者仍然不能存取你的帳號。

你可以在你的帳戶設定裡面的安全性分頁找到兩階段驗證的設定。

在點擊「Set up two-factor authentication」按鈕之後，他會連結到設定頁面，讓你可以設定手機 App 以產生第二階段驗證碼 （一個基於時間產生的一次性密碼），或者你也可以讓 GitHub 在你每次要登入時透過簡訊發送一個驗證碼給你。

當你選擇並完成 2FA 的設定之後，你的帳戶會變得更安全。並在之後的每次登入，除了密碼你還要提供一個驗證碼才能登入 GitHub。

如果你想要參與一個你沒有推送權限的專案，你可以「fork」一份。這代表說 GitHub 會複製一份這個專案的副本給你，並且你對這副本有全部的權限。這副本會存在於你的帳號下，你可以對它進行推送。

透過這方式，專案就不用去煩惱需要把所有協作者加入使用者來讓他們擁有推送的權限。 所有人可以 fork 專案，對 fork 出來的專案推送變更，然後去發出我們等下會提到的 Pull Request，來把這些變更貢獻回原本的專案裡。 這會開立一個能夠作程式碼審閱的討論串，然後擁有者能和貢獻者討論這個變更，直到擁有者覺得可以合併進原始專案裡面。

去到專案頁面，點下右上角的「Fork」鍵，就可以 fork 專案。

幾秒鐘之後，你就會被帶到你有寫入權限的新專案頁面。

GitHub 是基於一個以 Pull Request 為中心的特別合作流程而設計出來的。 這個流程，不論是你在一個緊密連結的團隊裡共同在單一倉儲上合作；或是一個由散布全球的陌生人們構成的合作網路或是公司，透過大量的 fork 專案來對專案做出貢獻，都能運作。 這一切都是基於我們在 使用 Git 分支 這章所講過的 主題分支 的工作流程。

一般情況下就是照著下面的程序運作的：

這基本上就是我們在 整合式管理員工作流程 這部分提過的整合式管理流程，不過我們是使用 GitHub 的網頁工具來做溝通或是變更審閱，而非電子郵件。

我們來看看下面的例子來了解如何使用這個流程來對 GitHub 上的專案做出變更吧。

現在我們已經講完關於對 GitHub 上的專案做貢獻的基本部份了。來看看一些讓你可以更有效率的使用 Pull Request 的小技巧吧。

連結其他議題，對於你在 GitHub 大多數的文字方塊裡能做的有趣事情而言，只是個開始。在議題、PR 描述、評論、程式碼評論，以及其他更多的地方，你都可以使用「GitHub 風格的 Markdown」。Markdown 能以純文字方式編輯，但能渲染出豐富的內容。

看看 一個顯示出 Markdwon 撰寫型式和渲染結果的範例 的範例來看看文字和評論能怎樣撰寫，並接著以 Markdwon 的方式渲染。

來建立一個拿來分享我們的原始碼的倉儲吧。 首先點擊主控面板右邊的「New Repository」；或是點擊頂端工具列裡面使用者名稱旁邊的 + 按鈕，如 「New repository」下拉式選單. 所示。

這會把你帶到「new repository」表單的所在頁面：

你只需要提供專案名稱，因為剩餘的欄位是完全選擇性的。 現在，你只要點下「Create Repository」鈕，然後碰地一聲——你就擁有了一個在 GitHub 上名為 <user>/<project_name> 的全新倉儲了。

因為你這個倉儲還沒有任何原始碼在裡面，GitHub 會展示一份關於如何建立一個全新的 Git 倉儲或是連結一個舊有 Git 專案的指引。 我們在這邊不會對這這部份多做描述，如果你需要回憶一下，去看看 Git 基礎 吧。

現在你的專案被託管在 GitHub 上了，你可以把網址給任何你想要分享專案的人。 所有人都可以透過 https://github.com/<user>/<project_name> 以 HTTP 方式存取，或是透過 git@github.com:<user>/<project_name> 以 SSH 方式存取。 Git 可以透過上述兩種途徑來推送及擷取資料，但所有操作都會透過對其連結的使用的驗證資訊來做存取控管。

你必須要把和你合作的人加入「協作者」，這樣他們才能對專案提交變更。 如果 Ben、Jeff 和 Louise 都有 GitHub 帳戶，而且你想要給他們推送變更的權限，你可以把他們加到你的專案。 把他們加入專案後，他們可以對專案「推送」變更，這意味著他們有這專案及專案的 Git 倉儲的讀寫權限。

點擊右側欄最下面的「Settings」連結。

接著選擇右邊選單的「Collaborators」。 然後在文字方塊裡輸入使用者名稱，按下「Add collaborator」。 你可以一直重複這個步驟來賦予所有你想要的人存取權限。 如果你要收回權限，只要點一下那個使用者右手邊的「X」即可。

現在你擁有一個裡面有些原始碼的專案，同時也可能會有些擁有推送權限的協作者。然後我們來看看當你收到 Pull Request 時要如何處理吧。

Pull Requests 可能是來自某個 fork 裡的分支，或是同個倉儲裡的某個分支。 兩者之間只差在，來自其他 fork 的 PR 通常你沒有對他們分支的推送權限，他們也沒有；而內部 PR 就是雙方都能存取分支。

關於這些東西的範例，我們就在這邊假設你是「tonychacon」而且你建立了一個名叫「fade」的 Arduino 原始碼專案吧。

GitHub 也有非常好的通知系統，讓徵詢特定人或團隊的意見變成一件易如反掌的事。

在任意一個專案裡，當你一輸入 @ 這個字元後，自動完成就會提供給你所有這個計畫的協作者和貢獻者的顯示名稱及使用者名稱。

你也可以提及某個並沒有出現在這個下拉式清單的使用者，不過自動完成通常會更快把牠抓出來。

當你發佈了一個有提到其他使用者的評論時，那些被標記的人會收到通知。 這意味著這會是一個非常有效率的把人拉入討論的方式，而非讓那些人主動追蹤討論進度。 在 GitHub 上人們很常把同團隊或是同公司的人拉近討論裡，藉以審閱 Pull Request 或是議題。

如果有人被標記，會被自動訂閱提到他們的 Pull Request 或是議題，之後就會收到所有相關的動態。 你也會自動訂閱所有你建立的東西、你觀注的版本庫或是你曾經發表過評論的東西。 如果你不想繼續收到通知，你可以按下頁面裡的「Unsubscribe」鈕來停止收到後續的更新。

當有些特殊檔案出現在你的版本庫時，GitHub 會注意到它們。

第一個就是 README 檔，它可以用任意一種可以被 GitHub 便是成文章的格式寫成。 舉例來說，它可以是 README、README.md、README.asciidoc、等等。 如果 GitHub 在你的原始碼裡發現 README 這個檔案時，他會被渲染再在專案首頁。

許多團隊用這檔案來整理所有這專案的相關資訊，來讓第一次接觸這個專案或版本庫的人了解這個專案。 通常會包含這些東西：

因為 GitHub 會渲染這個檔案，所以你可以嵌入圖片或連結來讓他更容易理解。

另個 GitHub 會辨識的特殊檔案就是 CONTRIBUTING。 如果你有個帶著任意種附檔名的 CONTRIBUTING，GitHub 會把它顯示成 在有 CONTRIBUTING 這個檔案時建立 Pull Request 給那些想建立 Pull Request 的使用者看。

這檔案就是你可以指定發給你這專案的 Pull Request 裡面可以包含哪些以及不能包含哪些東西。 這樣大家或許就會在建立 Pull Request 前看看這些原則了。

你在一個專案上通常沒有什麼管理性的事能做，不過這邊有幾個你或許有興趣的專案。

An organization is pretty easy to create; just click on the “+” icon at the top-right of any GitHub page, and select “New organization” from the menu.

First you’ll need to name your organization and provide an email address for a main point of contact for the group. Then you can invite other users to be co-owners of the account if you want to.

Follow these steps and you’ll soon be the owner of a brand-new organization. Like personal accounts, organizations are free if everything you plan to store there will be open source.

As an owner in an organization, when you fork a repository, you’ll have the choice of forking it to your organization’s namespace. When you create new repositories you can create them either under your personal account or under any of the organizations that you are an owner in. You also automatically “watch” any new repository created under these organizations.

Just like in 你的頭像, you can upload an avatar for your organization to personalize it a bit. Also just like personal accounts, you have a landing page for the organization that lists all of your repositories and can be viewed by other people.

Now let’s cover some of the things that are a bit different with an organizational account.

Organizations are associated with individual people by way of teams, which are simply a grouping of individual user accounts and repositories within the organization and what kind of access those people have in those repositories.

For example, say your company has three repositories: frontend, backend, and deployscripts. You’d want your HTML/CSS/JavaScript developers to have access to frontend and maybe backend, and your Operations people to have access to backend and deployscripts. Teams make this easy, without having to manage the collaborators for every individual repository.

The Organization page shows you a simple dashboard of all the repositories, users and teams that are under this organization.

To manage your Teams, you can click on the Teams sidebar on the right hand side of the page in The Organization page.. This will bring you to a page you can use to add members to the team, add repositories to the team or manage the settings and access control levels for the team. Each team can have read only, read/write or administrative access to the repositories. You can change that level by clicking the “Settings” button in The Team page..

When you invite someone to a team, they will get an email letting them know they’ve been invited.

Additionally, team @mentions (such as @acmecorp/frontend) work much the same as they do with individual users, except that all members of the team are then subscribed to the thread. This is useful if you want the attention from someone on a team, but you don’t know exactly who to ask.

A user can belong to any number of teams, so don’t limit yourself to only access-control teams. Special-interest teams like ux, css, or refactoring are useful for certain kinds of questions, and others like legal and colorblind for an entirely different kind.

Organizations also give owners access to all the information about what went on under the organization. You can go to the Audit Log tab and see what events have happened at an organization level, who did them and where in the world they were done.

You can also filter down to specific types of events, specific places or specific people.

The Hooks and Services section of GitHub repository administration is the easiest way to have GitHub interact with external systems.

Services and hooks give you a way to receive push notifications about events that happen on your repositories, but what if you need more information about these events? What if you need to automate something like adding collaborators or labeling issues?

This is where the GitHub API comes in handy. GitHub has tons of API endpoints for doing nearly anything you can do on the website in an automated fashion. In this section we’ll learn how to authenticate and connect to the API, how to comment on an issue and how to change the status of a Pull Request through the API.

The most basic thing you can do is a simple GET request on an endpoint that doesn’t require authentication. This could be a user or read-only information on an open source project. For example, if we want to know more about a user named “schacon”, we can run something like this:

There are tons of endpoints like this to get information about organizations, projects, issues, commits — just about anything you can publicly see on GitHub. You can even use the API to render arbitrary Markdown or find a .gitignore template.

However, if you want to do an action on the website such as comment on an Issue or Pull Request or if you want to view or interact with private content, you’ll need to authenticate.

There are several ways to authenticate. You can use basic authentication with just your username and password, but generally it’s a better idea to use a personal access token. You can generate this from the “Applications” tab of your settings page.

It will ask you which scopes you want for this token and a description. Make sure to use a good description so you feel comfortable removing the token when your script or application is no longer used.

GitHub will only show you the token once, so be sure to copy it. You can now use this to authenticate in your script instead of using a username and password. This is nice because you can limit the scope of what you want to do and the token is revocable.

This also has the added advantage of increasing your rate limit. Without authenticating, you will be limited to 60 requests per hour. If you authenticate you can make up to 5,000 requests per hour.

So let’s use it to make a comment on one of our issues. Let’s say we want to leave a comment on a specific issue, Issue #6. To do so we have to do an HTTP POST request to repos/<user>/<repo>/issues/<num>/comments with the token we just generated as an Authorization header.

Now if you go to that issue, you can see the comment that we just successfully posted as in A comment posted from the GitHub API..

You can use the API to do just about anything you can do on the website — creating and setting milestones, assigning people to Issues and Pull Requests, creating and changing labels, accessing commit data, creating new commits and branches, opening, closing or merging Pull Requests, creating and editing teams, commenting on lines of code in a Pull Request, searching the site and on and on.

There is one final example we’ll look at since it’s really useful if you’re working with Pull Requests. Each commit can have one or more statuses associated with it and there is an API to add and query that status.

Most of the Continuous Integration and testing services make use of this API to react to pushes by testing the code that was pushed, and then report back if that commit has passed all the tests. You could also use this to check if the commit message is properly formatted, if the submitter followed all your contribution guidelines, if the commit was validly signed — any number of things.

Let’s say you set up a webhook on your repository that hits a small web service that checks for a Signed-off-by string in the commit message.

Hopefully this is fairly simple to follow. In this web hook handler we look through each commit that was just pushed, we look for the string Signed-off-by in the commit message and finally we POST via HTTP to the /repos/<user>/<repo>/statuses/<commit_sha> API endpoint with the status.

In this case you can send a state (success, failure, error), a description of what happened, a target URL the user can go to for more information and a “context” in case there are multiple statuses for a single commit. For example, a testing service may provide a status and a validation service like this may also provide a status — the “context” field is how they’re differentiated.

If someone opens a new Pull Request on GitHub and this hook is set up, you may see something like Commit status via the API..

You can now see a little green check mark next to the commit that has a “Signed-off-by” string in the message and a red cross through the one where the author forgot to sign off. You can also see that the Pull Request takes the status of the last commit on the branch and warns you if it is a failure. This is really useful if you’re using this API for test results so you don’t accidentally merge something where the last commit is failing tests.

Though we’ve been doing nearly everything through curl and simple HTTP requests in these examples, several open-source libraries exist that make this API available in a more idiomatic way. At the time of this writing, the supported languages include Go, Objective-C, Ruby, and .NET. Check out http://github.com/octokit for more information on these, as they handle much of the HTTP for you.

Hopefully these tools can help you customize and modify GitHub to work better for your specific workflows. For complete documentation on the entire API as well as guides for common tasks, check out https://developer.github.com.

You can obviously refer to a commit by the SHA-1 hash that it’s given, but there are more human-friendly ways to refer to commits as well. This section outlines the various ways you can refer to a single commit.

Git is smart enough to figure out what commit you meant to type if you provide the first few characters, as long as your partial SHA-1 is at least four characters long and unambiguous – that is, only one object in the current repository begins with that partial SHA-1.

For example, to see a specific commit, suppose you run a git log command and identify the commit where you added certain functionality:

In this case, choose 1c002dd.... If you git show that commit, the following commands are equivalent (assuming the shorter versions are unambiguous):

Git can figure out a short, unique abbreviation for your SHA-1 values. If you pass --abbrev-commit to the git log command, the output will use shorter values but keep them unique; it defaults to using seven characters but makes them longer if necessary to keep the SHA-1 unambiguous:

Generally, eight to ten characters are more than enough to be unique within a project.

As an example, the Linux kernel, which is a pretty large project with over 450k commits and 3.6 million objects, has no two objects whose SHA-1s overlap more than the first 11 characters.

The most straightforward way to specify a commit requires that it has a branch reference pointed at it. Then, you can use a branch name in any Git command that expects a commit object or SHA-1 value. For instance, if you want to show the last commit object on a branch, the following commands are equivalent, assuming that the topic1 branch points to ca82a6d:

If you want to see which specific SHA-1 a branch points to, or if you want to see what any of these examples boils down to in terms of SHA-1s, you can use a Git plumbing tool called rev-parse. You can see Git Internals for more information about plumbing tools; basically, rev-parse exists for lower-level operations and isn’t designed to be used in day-to-day operations. However, it can be helpful sometimes when you need to see what’s really going on. Here you can run rev-parse on your branch.

One of the things Git does in the background while you’re working away is keep a “reflog” – a log of where your HEAD and branch references have been for the last few months.

You can see your reflog by using git reflog:

Every time your branch tip is updated for any reason, Git stores that information for you in this temporary history. And you can specify older commits with this data, as well. If you want to see the fifth prior value of the HEAD of your repository, you can use the @{n} reference that you see in the reflog output:

You can also use this syntax to see where a branch was some specific amount of time ago. For instance, to see where your master branch was yesterday, you can type

That shows you where the branch tip was yesterday. This technique only works for data that’s still in your reflog, so you can’t use it to look for commits older than a few months.

To see reflog information formatted like the git log output, you can run git log -g:

It’s important to note that the reflog information is strictly local – it’s a log of what you’ve done in your repository. The references won’t be the same on someone else’s copy of the repository; and right after you initially clone a repository, you’ll have an empty reflog, as no activity has occurred yet in your repository. Running git show HEAD@{2.months.ago} will work only if you cloned the project at least two months ago – if you cloned it five minutes ago, you’ll get no results.

The other main way to specify a commit is via its ancestry. If you place a ^ at the end of a reference, Git resolves it to mean the parent of that commit. Suppose you look at the history of your project:

Then, you can see the previous commit by specifying HEAD^, which means “the parent of HEAD”:

You can also specify a number after the ^ – for example, d921970^2 means “the second parent of d921970.” This syntax is only useful for merge commits, which have more than one parent. The first parent is the branch you were on when you merged, and the second is the commit on the branch that you merged in:

The other main ancestry specification is the ~. This also refers to the first parent, so HEAD~ and HEAD^ are equivalent. The difference becomes apparent when you specify a number. HEAD~2 means “the first parent of the first parent,” or “the grandparent” – it traverses the first parents the number of times you specify. For example, in the history listed earlier, HEAD~3 would be

This can also be written HEAD^^^, which again is the first parent of the first parent of the first parent:

You can also combine these syntaxes – you can get the second parent of the previous reference (assuming it was a merge commit) by using HEAD~3^2, and so on.

Now that you can specify individual commits, let’s see how to specify ranges of commits. This is particularly useful for managing your branches – if you have a lot of branches, you can use range specifications to answer questions such as, “What work is on this branch that I haven’t yet merged into my main branch?”

If you type 2 or u at the What now> prompt, the script prompts you for which files you want to stage:

To stage the TODO and index.html files, you can type the numbers:

The * next to each file means the file is selected to be staged. If you press Enter after typing nothing at the Update>> prompt, Git takes anything selected and stages it for you:

Now you can see that the TODO and index.html files are staged and the simplegit.rb file is still unstaged. If you want to unstage the TODO file at this point, you use the 3 or r (for revert) option:

Looking at your Git status again, you can see that you’ve unstaged the TODO file:

To see the diff of what you’ve staged, you can use the 6 or d (for diff) command. It shows you a list of your staged files, and you can select the ones for which you would like to see the staged diff. This is much like specifying git diff --cached on the command line:

With these basic commands, you can use the interactive add mode to deal with your staging area a little more easily.

It’s also possible for Git to stage certain parts of files and not the rest. For example, if you make two changes to your simplegit.rb file and want to stage one of them and not the other, doing so is very easy in Git. From the interactive prompt, type 5 or p (for patch). Git will ask you which files you would like to partially stage; then, for each section of the selected files, it will display hunks of the file diff and ask if you would like to stage them, one by one:

You have a lot of options at this point. Typing ? shows a list of what you can do:

Generally, you’ll type y or n if you want to stage each hunk, but staging all of them in certain files or skipping a hunk decision until later can be helpful too. If you stage one part of the file and leave another part unstaged, your status output will look like this:

The status of the simplegit.rb file is interesting. It shows you that a couple of lines are staged and a couple are unstaged. You’ve partially staged this file. At this point, you can exit the interactive adding script and run git commit to commit the partially staged files.

You also don’t need to be in interactive add mode to do the partial-file staging – you can start the same script by using git add -p or git add --patch on the command line.

Furthermore, you can use patch mode for partially resetting files with the reset --patch command, for checking out parts of files with the checkout --patch command and for stashing parts of files with the stash save --patch command. We’ll go into more details on each of these as we get to more advanced usages of these commands.

To demonstrate, you’ll go into your project and start working on a couple of files and possibly stage one of the changes. If you run git status, you can see your dirty state:

Now you want to switch branches, but you don’t want to commit what you’ve been working on yet; so you’ll stash the changes. To push a new stash onto your stack, run git stash or git stash save:

Your working directory is clean:

At this point, you can easily switch branches and do work elsewhere; your changes are stored on your stack. To see which stashes you’ve stored, you can use git stash list:

In this case, two stashes were done previously, so you have access to three different stashed works. You can reapply the one you just stashed by using the command shown in the help output of the original stash command: git stash apply. If you want to apply one of the older stashes, you can specify it by naming it, like this: git stash apply stash@{2}. If you don’t specify a stash, Git assumes the most recent stash and tries to apply it:

You can see that Git re-modifies the files you reverted when you saved the stash. In this case, you had a clean working directory when you tried to apply the stash, and you tried to apply it on the same branch you saved it from; but having a clean working directory and applying it on the same branch aren’t necessary to successfully apply a stash. You can save a stash on one branch, switch to another branch later, and try to reapply the changes. You can also have modified and uncommitted files in your working directory when you apply a stash – Git gives you merge conflicts if anything no longer applies cleanly.

The changes to your files were reapplied, but the file you staged before wasn’t restaged. To do that, you must run the git stash apply command with a --index option to tell the command to try to reapply the staged changes. If you had run that instead, you’d have gotten back to your original position:

The apply option only tries to apply the stashed work – you continue to have it on your stack. To remove it, you can run git stash drop with the name of the stash to remove:

You can also run git stash pop to apply the stash and then immediately drop it from your stack.

There are a few stash variants that may also be helpful. The first option that is quite popular is the --keep-index option to the stash save command. This tells Git to not stash anything that you’ve already staged with the git add command.

This can be really helpful if you’ve made a number of changes but want to only commit some of them and then come back to the rest of the changes at a later time.

Another common thing you may want to do with stash is to stash the untracked files as well as the tracked ones. By default, git stash will only store files that are already in the index. If you specify --include-untracked or -u, Git will also stash any untracked files you have created.

Finally, if you specify the --patch flag, Git will not stash everything that is modified but will instead prompt you interactively which of the changes you would like to stash and which you would like to keep in your working directory.

If you stash some work, leave it there for a while, and continue on the branch from which you stashed the work, you may have a problem reapplying the work. If the apply tries to modify a file that you’ve since modified, you’ll get a merge conflict and will have to try to resolve it. If you want an easier way to test the stashed changes again, you can run git stash branch, which creates a new branch for you, checks out the commit you were on when you stashed your work, reapplies your work there, and then drops the stash if it applies successfully:

This is a nice shortcut to recover stashed work easily and work on it in a new branch.

Finally, you may not want to stash some work or files in your working directory, but simply get rid of them. The git clean command will do this for you.

Some common reasons for this might be to remove cruft that has been generated by merges or external tools or to remove build artifacts in order to run a clean build.

You’ll want to be pretty careful with this command, since it’s designed to remove files from your working directory that are not tracked. If you change your mind, there is often no retrieving the content of those files. A safer option is to run git stash --all to remove everything but save it in a stash.

Assuming you do want to remove cruft files or clean your working directory, you can do so with git clean. To remove all the untracked files in your working directory, you can run git clean -f -d, which removes any files and also any subdirectories that become empty as a result. The -f means force or "really do this".

If you ever want to see what it would do, you can run the command with the -n option, which means “do a dry run and tell me what you would have removed”.

By default, the git clean command will only remove untracked files that are not ignored. Any file that matches a pattern in your .gitignore or other ignore files will not be removed. If you want to remove those files too, such as to remove all .o files generated from a build so you can do a fully clean build, you can add a -x to the clean command.

If you don’t know what the git clean command is going to do, always run it with a -n first to double check before changing the -n to a -f and doing it for real. The other way you can be careful about the process is to run it with the -i or “interactive” flag.

This will run the clean command in an interactive mode.

This way you can step through each file individually or specify patterns for deletion interactively.

First of all, if you want to sign anything you need to get GPG configured and your personal key installed.

If you don’t have a key installed, you can generate one with gpg --gen-key.

Once you have a private key to sign with, you can configure Git to use it for signing things by setting the user.signingkey config setting.

Now Git will use your key by default to sign tags and commits if you want.

If you have a GPG private key setup, you can now use it to sign new tags. All you have to do is use -s instead of -a:

If you run git show on that tag, you can see your GPG signature attached to it:

To verify a signed tag, you use git tag -v [tag-name]. This command uses GPG to verify the signature. You need the signer’s public key in your keyring for this to work properly:

If you don’t have the signer’s public key, you get something like this instead:

In more recent versions of Git (v1.7.9 and above), you can now also sign individual commits. If you’re interested in signing commits directly instead of just the tags, all you need to do is add a -S to your git commit command.

To see and verify these signatures, there is also a --show-signature option to git log.

Additionally, you can configure git log to check any signatures it finds and list them in its output with the %G? format.

Here we can see that only the latest commit is signed and valid and the previous commits are not.

In Git 1.8.3 and later, "git merge" and "git pull" can be told to inspect and reject when merging a commit that does not carry a trusted GPG signature with the --verify-signatures command.

If you use this option when merging a branch and it contains commits that are not signed and valid, the merge will not work.

If the merge contains only valid signed commits, the merge command will show you all the signatures it has checked and then move forward with the merge.

You can also use the -S option with the git merge command itself to sign the resulting merge commit itself. The following example both verifies that every commit in the branch to be merged is signed and furthermore signs the resulting merge commit.

Signing tags and commits is great, but if you decide to use this in your normal workflow, you’ll have to make sure that everyone on your team understands how to do so. If you don’t, you’ll end up spending a lot of time helping people figure out how to rewrite their commits with signed versions. Make sure you understand GPG and the benefits of signing things before adopting this as part of your standard workflow.

Git ships with a command called grep that allows you to easily search through any committed tree or the working directory for a string or regular expression. For these examples, we’ll look through the Git source code itself.

By default, it will look through the files in your working directory. You can pass -n to print out the line numbers where Git has found matches.

There are a number of interesting options you can provide the grep command.

For instance, instead of the previous call, you can have Git summarize the output by just showing you which files matched and how many matches there were in each file with the --count option:

If you want to see what method or function it thinks it has found a match in, you can pass -p:

So here we can see that gmtime_r is called in the match_multi_number and match_digit functions in the date.c file.

You can also look for complex combinations of strings with the --and flag, which makes sure that multiple matches are in the same line. For instance, let’s look for any lines that define a constant with either the strings “LINK” or “BUF_MAX” in them in the Git codebase in an older 1.8.0 version.

Here we’ll also use the --break and --heading options which help split up the output into a more readable format.

The git grep command has a few advantages over normal searching commands like grep and ack. The first is that it’s really fast, the second is that you can search through any tree in Git, not just the working directory. As we saw in the above example, we looked for terms in an older version of the Git source code, not the version that was currently checked out.

Perhaps you’re looking not for where a term exists, but when it existed or was introduced. The git log command has a number of powerful tools for finding specific commits by the content of their messages or even the content of the diff they introduce.

If we want to find out for example when the ZLIB_BUF_MAX constant was originally introduced, we can tell Git to only show us the commits that either added or removed that string with the -S option.

If we look at the diff of those commits we can see that in ef49a7a the constant was introduced and in e01503b it was modified.

If you need to be more specific, you can provide a regular expression to search for with the -G option.

Changing your last commit is probably the most common rewriting of history that you’ll do. You’ll often want to do two basic things to your last commit: change the commit message, or change the snapshot you just recorded by adding, changing and removing files.

If you only want to modify your last commit message, it’s very simple:

That drops you into your text editor, which has your last commit message in it, ready for you to modify the message. When you save and close the editor, the editor writes a new commit containing that message and makes it your new last commit.

If you’ve committed and then you want to change the snapshot you committed by adding or changing files, possibly because you forgot to add a newly created file when you originally committed, the process works basically the same way. You stage the changes you want by editing a file and running git add on it or git rm to a tracked file, and the subsequent git commit --amend takes your current staging area and makes it the snapshot for the new commit.

You need to be careful with this technique because amending changes the SHA-1 of the commit. It’s like a very small rebase – don’t amend your last commit if you’ve already pushed it.

To modify a commit that is farther back in your history, you must move to more complex tools. Git doesn’t have a modify-history tool, but you can use the rebase tool to rebase a series of commits onto the HEAD they were originally based on instead of moving them to another one. With the interactive rebase tool, you can then stop after each commit you want to modify and change the message, add files, or do whatever you wish. You can run rebase interactively by adding the -i option to git rebase. You must indicate how far back you want to rewrite commits by telling the command which commit to rebase onto.

For example, if you want to change the last three commit messages, or any of the commit messages in that group, you supply as an argument to git rebase -i the parent of the last commit you want to edit, which is HEAD~2^ or HEAD~3. It may be easier to remember the ~3 because you’re trying to edit the last three commits; but keep in mind that you’re actually designating four commits ago, the parent of the last commit you want to edit:

Remember again that this is a rebasing command – every commit included in the range HEAD~3..HEAD will be rewritten, whether you change the message or not. Don’t include any commit you’ve already pushed to a central server – doing so will confuse other developers by providing an alternate version of the same change.

Running this command gives you a list of commits in your text editor that looks something like this:

It’s important to note that these commits are listed in the opposite order than you normally see them using the log command. If you run a log, you see something like this:

Notice the reverse order. The interactive rebase gives you a script that it’s going to run. It will start at the commit you specify on the command line (HEAD~3) and replay the changes introduced in each of these commits from top to bottom. It lists the oldest at the top, rather than the newest, because that’s the first one it will replay.

You need to edit the script so that it stops at the commit you want to edit. To do so, change the word ‘pick’ to the word ‘edit’ for each of the commits you want the script to stop after. For example, to modify only the third commit message, you change the file to look like this:

When you save and exit the editor, Git rewinds you back to the last commit in that list and drops you on the command line with the following message:

These instructions tell you exactly what to do. Type

Change the commit message, and exit the editor. Then, run

This command will apply the other two commits automatically, and then you’re done. If you change pick to edit on more lines, you can repeat these steps for each commit you change to edit. Each time, Git will stop, let you amend the commit, and continue when you’re finished.

You can also use interactive rebases to reorder or remove commits entirely. If you want to remove the “added cat-file” commit and change the order in which the other two commits are introduced, you can change the rebase script from this

to this:

When you save and exit the editor, Git rewinds your branch to the parent of these commits, applies 310154e and then f7f3f6d, and then stops. You effectively change the order of those commits and remove the “added cat-file” commit completely.

It’s also possible to take a series of commits and squash them down into a single commit with the interactive rebasing tool. The script puts helpful instructions in the rebase message:

If, instead of “pick” or “edit”, you specify “squash”, Git applies both that change and the change directly before it and makes you merge the commit messages together. So, if you want to make a single commit from these three commits, you make the script look like this:

When you save and exit the editor, Git applies all three changes and then puts you back into the editor to merge the three commit messages:

When you save that, you have a single commit that introduces the changes of all three previous commits.

Splitting a commit undoes a commit and then partially stages and commits as many times as commits you want to end up with. For example, suppose you want to split the middle commit of your three commits. Instead of “updated README formatting and added blame”, you want to split it into two commits: “updated README formatting” for the first, and “added blame” for the second. You can do that in the rebase -i script by changing the instruction on the commit you want to split to “edit”:

Then, when the script drops you to the command line, you reset that commit, take the changes that have been reset, and create multiple commits out of them. When you save and exit the editor, Git rewinds to the parent of the first commit in your list, applies the first commit (f7f3f6d), applies the second (310154e), and drops you to the console. There, you can do a mixed reset of that commit with git reset HEAD^, which effectively undoes that commit and leaves the modified files unstaged. Now you can stage and commit files until you have several commits, and run git rebase --continue when you’re done:

Git applies the last commit (a5f4a0d) in the script, and your history looks like this:

Once again, this changes the SHA-1s of all the commits in your list, so make sure no commit shows up in that list that you’ve already pushed to a shared repository.

There is another history-rewriting option that you can use if you need to rewrite a larger number of commits in some scriptable way – for instance, changing your email address globally or removing a file from every commit. The command is filter-branch, and it can rewrite huge swaths of your history, so you probably shouldn’t use it unless your project isn’t yet public and other people haven’t based work off the commits you’re about to rewrite. However, it can be very useful. You’ll learn a few of the common uses so you can get an idea of some of the things it’s capable of.

An easier way to think about reset and checkout is through the mental frame of Git being a content manager of three different trees. By “tree” here we really mean “collection of files”, not specifically the data structure. (There are a few cases where the index doesn’t exactly act like a tree, but for our purposes it is easier to think about it this way for now.)

Git as a system manages and manipulates three trees in its normal operation:

Git’s main purpose is to record snapshots of your project in successively better states, by manipulating these three trees.

Let’s visualize this process: say you go into a new directory with a single file in it. We’ll call this v1 of the file, and we’ll indicate it in blue. Now we run git init, which will create a Git repository with a HEAD reference which points to an unborn branch (master doesn’t exist yet).

At this point, only the Working Directory tree has any content.

Now we want to commit this file, so we use git add to take content in the Working Directory and copy it to the Index.

Then we run git commit, which takes the contents of the Index and saves it as a permanent snapshot, creates a commit object which points to that snapshot, and updates master to point to that commit.

If we run git status, we’ll see no changes, because all three trees are the same.

Now we want to make a change to that file and commit it. We’ll go through the same process; first we change the file in our working directory. Let’s call this v2 of the file, and indicate it in red.

If we run git status right now, we’ll see the file in red as “Changes not staged for commit,” because that entry differs between the Index and the Working Directory. Next we run git add on it to stage it into our Index.

At this point if we run git status we will see the file in green under “Changes to be committed” because the Index and HEAD differ – that is, our proposed next commit is now different from our last commit. Finally, we run git commit to finalize the commit.

Now git status will give us no output, because all three trees are the same again.

Switching branches or cloning goes through a similar process. When you checkout a branch, it changes HEAD to point to the new branch ref, populates your Index with the snapshot of that commit, then copies the contents of the Index into your Working Directory.

The reset command makes more sense when viewed in this context.

For the purposes of these examples, let’s say that we’ve modified file.txt again and committed it a third time. So now our history looks like this:

Let’s now walk through exactly what reset does when you call it. It directly manipulates these three trees in a simple and predictable way. It does up to three basic operations.

That covers the behavior of reset in its basic form, but you can also provide it with a path to act upon. If you specify a path, reset will skip step 1, and limit the remainder of its actions to a specific file or set of files. This actually sort of makes sense – HEAD is just a pointer, and you can’t point to part of one commit and part of another. But the Index and Working directory can be partially updated, so reset proceeds with steps 2 and 3.

So, assume we run git reset file.txt. This form (since you did not specify a commit SHA-1 or branch, and you didn’t specify --soft or --hard) is shorthand for git reset --mixed HEAD file.txt, which will:

So it essentially just copies file.txt from HEAD to the Index.

This has the practical effect of unstaging the file. If we look at the diagram for that command and think about what git add does, they are exact opposites.

This is why the output of the git status command suggests that you run this to unstage a file. (See 將已預存的檔案移出預存區 for more on this.)

We could just as easily not let Git assume we meant “pull the data from HEAD” by specifying a specific commit to pull that file version from. We would just run something like git reset eb43bf file.txt.

This effectively does the same thing as if we had reverted the content of the file to v1 in the Working Directory, ran git add on it, then reverted it back to v3 again (without actually going through all those steps). If we run git commit now, it will record a change that reverts that file back to v1, even though we never actually had it in our Working Directory again.

It’s also interesting to note that like git add, the reset command will accept a --patch option to unstage content on a hunk-by-hunk basis. So you can selectively unstage or revert content.

Let’s look at how to do something interesting with this newfound power – squashing commits.

Say you have a series of commits with messages like “oops.”, “WIP” and “forgot this file”. You can use reset to quickly and easily squash them into a single commit that makes you look really smart. (Squashing Commits shows another way to do this, but in this example it’s simpler to use reset.)

Let’s say you have a project where the first commit has one file, the second commit added a new file and changed the first, and the third commit changed the first file again. The second commit was a work in progress and you want to squash it down.

You can run git reset --soft HEAD~2 to move the HEAD branch back to an older commit (the first commit you want to keep):

And then simply run git commit again:

Now you can see that your reachable history, the history you would push, now looks like you had one commit with file-a.txt v1, then a second that both modified file-a.txt to v3 and added file-b.txt. The commit with the v2 version of the file is no longer in the history.

Finally, you may wonder what the difference between checkout and reset is. Like reset, checkout manipulates the three trees, and it is a bit different depending on whether you give the command a file path or not.

Hopefully now you understand and feel more comfortable with the reset command, but are probably still a little confused about how exactly it differs from checkout and could not possibly remember all the rules of the different invocations.

Here’s a cheat-sheet for which commands affect which trees. The “HEAD” column reads “REF” if that command moves the reference (branch) that HEAD points to, and “HEAD” if it moves HEAD itself. Pay especial attention to the WD Safe? column – if it says NO, take a second to think before running that command.

While we covered some basics on resolving merge conflicts in 合併衝突的基本解法, for more complex conflicts, Git provides a few tools to help you figure out what’s going on and how to better deal with the conflict.

First of all, if at all possible, try to make sure your working directory is clean before doing a merge that may have conflicts. If you have work in progress, either commit it to a temporary branch or stash it. This makes it so that you can undo anything you try here. If you have unsaved changes in your working directory when you try a merge, some of these tips may help you lose that work.

Let’s walk through a very simple example. We have a super simple Ruby file that prints hello world.

In our repository, we create a new branch named whitespace and proceed to change all the Unix line endings to DOS line endings, essentially changing every line of the file, but just with whitespace. Then we change the line “hello world” to “hello mundo”.

Now we switch back to our master branch and add some documentation for the function.

Now we try to merge in our whitespace branch and we’ll get conflicts because of the whitespace changes.

Now that you know how to create a merge commit, you’ll probably make some by mistake. One of the great things about working with Git is that it’s okay to make mistakes, because it’s possible (and in many cases easy) to fix them.

Merge commits are no different. Let’s say you started work on a topic branch, accidentally merged it into master, and now your commit history looks like this:

There are two ways to approach this problem, depending on what your desired outcome is.

So far we’ve covered the normal merge of two branches, normally handled with what is called the “recursive” strategy of merging. There are other ways to merge branches together however. Let’s cover a few of them quickly.

If you track down a bug in your code and want to know when it was introduced and why, file annotation is often your best tool. It shows you what commit was the last to modify each line of any file. So, if you see that a method in your code is buggy, you can annotate the file with git blame to see when each line of the method was last edited and by whom. This example uses the -L option to limit the output to lines 12 through 22:

Notice that the first field is the partial SHA-1 of the commit that last modified that line. The next two fields are values extracted from that commit–the author name and the authored date of that commit – so you can easily see who modified that line and when. After that come the line number and the content of the file. Also note the ^4832fe2 commit lines, which designate that those lines were in this file’s original commit. That commit is when this file was first added to this project, and those lines have been unchanged since. This is a tad confusing, because now you’ve seen at least three different ways that Git uses the ^ to modify a commit SHA-1, but that is what it means here.

Another cool thing about Git is that it doesn’t track file renames explicitly. It records the snapshots and then tries to figure out what was renamed implicitly, after the fact. One of the interesting features of this is that you can ask it to figure out all sorts of code movement as well. If you pass -C to git blame, Git analyzes the file you’re annotating and tries to figure out where snippets of code within it originally came from if they were copied from elsewhere. For example, say you are refactoring a file named GITServerHandler.m into multiple files, one of which is GITPackUpload.m. By blaming GITPackUpload.m with the -C option, you can see where sections of the code originally came from:

This is really useful. Normally, you get as the original commit the commit where you copied the code over, because that is the first time you touched those lines in this file. Git tells you the original commit where you wrote those lines, even if it was in another file.

Annotating a file helps if you know where the issue is to begin with. If you don’t know what is breaking, and there have been dozens or hundreds of commits since the last state where you know the code worked, you’ll likely turn to git bisect for help. The bisect command does a binary search through your commit history to help you identify as quickly as possible which commit introduced an issue.

Let’s say you just pushed out a release of your code to a production environment, you’re getting bug reports about something that wasn’t happening in your development environment, and you can’t imagine why the code is doing that. You go back to your code, and it turns out you can reproduce the issue, but you can’t figure out what is going wrong. You can bisect the code to find out. First you run git bisect start to get things going, and then you use git bisect bad to tell the system that the current commit you’re on is broken. Then, you must tell bisect when the last known good state was, using git bisect good [good_commit]:

Git figured out that about 12 commits came between the commit you marked as the last good commit (v1.0) and the current bad version, and it checked out the middle one for you. At this point, you can run your test to see if the issue exists as of this commit. If it does, then it was introduced sometime before this middle commit; if it doesn’t, then the problem was introduced sometime after the middle commit. It turns out there is no issue here, and you tell Git that by typing git bisect good and continue your journey:

Now you’re on another commit, halfway between the one you just tested and your bad commit. You run your test again and find that this commit is broken, so you tell Git that with git bisect bad:

This commit is fine, and now Git has all the information it needs to determine where the issue was introduced. It tells you the SHA-1 of the first bad commit and show some of the commit information and which files were modified in that commit so you can figure out what happened that may have introduced this bug:

When you’re finished, you should run git bisect reset to reset your HEAD to where you were before you started, or you’ll end up in a weird state:

This is a powerful tool that can help you check hundreds of commits for an introduced bug in minutes. In fact, if you have a script that will exit 0 if the project is good or non-0 if the project is bad, you can fully automate git bisect. First, you again tell it the scope of the bisect by providing the known bad and good commits. You can do this by listing them with the bisect start command if you want, listing the known bad commit first and the known good commit second:

Doing so automatically runs test-error.sh on each checked-out commit until Git finds the first broken commit. You can also run something like make or make tests or whatever you have that runs automated tests for you.