Git使用手冊__git

GitUserManualChinese - Robin Wiki GitUserManualChinese

Git 使用者手冊（1.5.3 及後續版本適用）

翻譯: 羅崢嶸 (Robin Steven) < vortune@gmail.com >

英文版本: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

 

  Preface 前言

Git is a fast distributed revision control system.

Git 是一個快速的分布式版本控制系統

This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git.

這個手冊是面向那些具有基本的 Unix 命令列使用技能，但是沒有 Git 知識的人設計的。

Chapter 1, Repositories and Branches and Chapter 2, Exploring git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for regressions, and so on.

第一章 版本庫與分支 和 第二章 考查 git 曆史 將展示如何用 git 來擷取和研究一個項目，通過閱讀這些章節，我們學習如何建立和測試一個具體的軟體項目的版本，學習“撤退”等等。

People needing to do actual development will also want to read Chapter 3, Developing with git and Chapter 4, Sharing development with others.

人們是需要開展真正的研發工作的，那麼就學習 第三章， 用 git 進行開發 和 第四章，與他人共用研發成果。

Further chapters cover more specialized topics.

更多的一些章節會涉及到許多的專題話題。

Comprehensive reference documentation is available through the man pages, or git-help(1) command. For example, for the command "git clone <repo>", you can either use:

參考文檔可以通過系統的手冊頁命令，或者是 git-help(1) 命令來查看。譬如，你想參考 "git clone <repo>"， 你可以用下面的兩種方式：

 

$ man git-clone

or: 或者：

 

$ git help clone

With the latter, you can use the manual viewer of your choice; see git-help(1) for more information.

晚一點你就有機會用到這些手冊查看器的；看 git-help(1) 會得到比較多的資訊。

See also Appendix A, Git Quick Reference for a brief overview of git commands, without any explanation.

閱讀 附錄A，那裡是一個 git 命令的快速縱覽，但是它不帶任何的解說。

Finally, see Appendix B, Notes and todo list for this manual for ways that you can help make this manual more complete.

最後，看看 附錄B，這份手冊的工作備忘和計劃，通過它你可以協助這份文檔變得更完善。

  Chapter 1. Repositories and Branches 第一章. 版本庫與分支

  How to get a git repository 如何擷取一個版本庫

It will be useful to have a git repository to experiment with as you read this manual.

有一個實驗性的 git 版本庫對我們閱讀這份手冊將非常有用。

The best way to get one is by using the git-clone(1) command to download a copy of an existing repository. If you don't already have a project in mind, here are some interesting examples:

擷取一個已經存在的版本庫，最佳的方法是用 git-clone 命令，如果你還沒有什麼心目中的項目的話，那麼這裡有些有趣的例子：

 

        # git itself (approx. 10MB download):$ git clone git://git.kernel.org/pub/scm/git/git.git        # the Linux kernel (approx. 150MB download):$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

The initial clone may be time-consuming for a large project, but you will only need to clone once.

對於一個大型項目來說，初始性的複製是挺費時的，不過複製只需要做一次。

The clone command creates a new directory named after the project ("git" or "linux-2.6" in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, called the working tree, together with a special top-level directory named ".git", which contains all the information about the history of the project.

克 隆命令會建立一個新的目錄，並根據項目的名稱來命名這個項目（譬如上說例子中的 “git” 和 “linux-2.6”）。當你進入這個目錄的時候，你可以看到它已經包含了項目的所有檔案，我們稱之為工作樹，在頂層目錄中還連帶了一個叫 ".git" 的特殊的目錄，裡麵包含了項目的發展曆史的所有資訊。

  How to check out a different version of a project 如何提取項目的不同版本

Git is best thought of as a tool for storing the history of a collection of files. It stores the history as a compressed collection of interrelated snapshots of the project's contents. In git each such version is called a commit.

最好將 git 當作是檔案發展的曆史紀錄的收集工具，它壓縮並儲存了項目的發展的關聯性快照。在 git 中，每個這些變更稱作交付(commit)。

Those snapshots aren't necessarily all arranged in a single line from oldest to newest; instead, work may simultaneously proceed along parallel lines of development, called branches, which may merge and diverge.

這些快照並不需要按從舊到新單線索地發展；它可以是同步並行地發展的，稱之為分支，它們是可以合并和分割的。

A single git repository can track development on multiple branches. It does this by keeping a list of heads which reference the latest commit on each branch; the git-branch(1) command shows you the list of branch heads:

一個 git 版本庫可以跟蹤多個分支的發展，它通過儲存一個分支頭列表的方式來做到這一點，每個分支頭都是一個引用(reference)，它指向該分支最後的一個交付(commit)； git-branch(1) 命令可以向你展示每個分支頭：

 

$ git branch* master

A freshly cloned repository contains a single branch head, by default named "master", with the working directory initialized to the state of the project referred to by that branch head.

一個剛剛複製的版本庫只包含一個分支頭，預設叫 “master” （主分支），並且工作目錄已經被初始化為這個分支頭所指向的項目狀態。

Most projects also use tags. Tags, like heads, are references into the project's history, and can be listed using the git-tag(1) command:

大部分的項目還用到標籤（tags）。標籤（Tags）就好像頭（heads），它指向項目的某個曆史場面，它們可以通過 git-tag(1) 命令列舉出來：

 

$ git tag -lv2.6.11v2.6.11-treev2.6.12v2.6.12-rc2v2.6.12-rc3v2.6.12-rc4v2.6.12-rc5v2.6.12-rc6v2.6.13...

Tags are expected to always point at the same version of a project, while heads are expected to advance as development progresses.

Tags 被當做是項目統一的版本來對待，而 heads 則是項目前進的每一個步伐。

Create a new branch head pointing to one of these versions and check it out using git-checkout(1):

下面建立一個新的分支頭，使其指向其中的某個版本，同時將它提取出來，可以用 git-checkout(1) 命令：

 

$ git checkout -b new v2.6.13

The working directory then reflects the contents that the project had when it was tagged v2.6.13, and git-branch(1) shows two branches, with an asterisk marking the currently checked-out branch:

工作目錄將被鏡像為項目中標記為 v2.6.13 的版本的內容，用 git-branch(1) 命令展示這個兩個分支，前面帶星號(*)的就是當前抽取的分支。

 

$ git branch  master* new

If you decide that you'd rather see version 2.6.17, you can modify the current branch to point at v2.6.17 instead, with

如果你打算看看 2.6.17 的版本，你可以遷移你當前的分支，讓它指向 2.6.17, 使用一下命令：

 

$ git reset --hard v2.6.17

Note that if the current branch head was your only reference to a particular point in history, then resetting that branch may leave you with no way to find the history it used to point to; so use this command carefully.

注意，如果當前的分支頭是你唯一的指向具體的曆史場面的引用的話，那麼複位 (resetting) 這個分支將令你無法找回這個分支以前的所有曆史紀錄，所以這個命令要慎用。

  Understanding History: Commits 理解曆史： 交付

Every change in the history of a project is represented by a commit. The git-show(1) command shows the most recent commit on the current branch:

項目的每一個曆史變更體現為每一個交付 (commit)。git-show(1) 命令展示當前分支的最新交付：

 

$ git showcommit 17cf781661e6d38f737f15f53ab552f1e95960d7Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>Date:   Tue Apr 19 14:11:06 2005 -0700    Remove duplicate getenv(DB_ENVIRONMENT) call    Noted by Tony Luck.diff --git a/init-db.c b/init-db.cindex 65898fa..b002dc6 100644--- a/init-db.c+++ b/init-db.c@@ -7,7 +7,7 @@ int main(int argc, char **argv) {-       char *sha1_dir = getenv(DB_ENVIRONMENT), *path;+       char *sha1_dir, *path;        int len, i;        if (mkdir(".git", 0755) < 0) {

As you can see, a commit shows who made the latest change, what they did, and why.

正如你看到的那樣，交付表明了誰做的最後的更改，改了什麼，為什麼改。

Every commit has a 40-hexdigit id, sometimes called the "object name" or the "SHA1 id", shown on the first line of the "git-show" output. You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for example in email), then you are guaranteed that name will refer to the same commit in their repository that it does in yours (assuming their repository has that commit at all). Since the object name is computed as a hash over the contents of the commit, you are guaranteed that the commit can never change without its name also changing.

每 個交付都有一個40個16進位字元的標識號，稱為 “對象名” 或者叫 “SHA1 id”，它顯示在 git-show 命令的輸出的第一行中。你通常可以用較簡短的名字來指明一個交付，譬如標籤和分支的名稱等等，但是這個長長的名字是很有用的。最重要的是，對於某個交付來 說它是全域唯一的名字： 譬如你告訴其他人某個對象名（通過 email等方式），那麼你需要確保這個名字不管是在你的版本庫中，還是在他們的版本庫中都是指向同一個交付的（假設他們的版本庫也被提交了很多東西）。 當對象名根據每個交付的內容通過雜湊演算法（hash）算出之後，你就可以確保每個交付中的內容的修改都不可能脫離它的名字。

In fact, in Chapter 7, Git concepts we shall see that everything stored in git history, including file data and directory contents, is stored in an object with a name that is a hash of its contents.

事實上，在 第七章，Git 的概念 中，我們可以看到儲存在 git 曆史中的所有東西，包括檔案資料與目錄內容都會被儲存為對象，對象名就是他們的內容的雜湊特徵值。

  Understanding history: commits, parents, and reachability 交付，父交付與可及性

Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. Following the chain of parents will eventually take you back to the beginning of the project.

每個交付（除非是項目的第一個交付）總是有他的父交付，這樣就說明了到當前的交付為止到底發生過什麼。追索父交付鏈，可以將我們帶回項目的起始點。

However, the commits do not form a simple list; git allows lines of development to diverge and then reconverge, and the point where two lines of development reconverge is called a "merge". The commit representing a merge can therefore have more than one parent, with each parent representing the most recent commit on one of the lines of development leading to that point.

無論如何，這些交付的組織形式都不會是簡單的；git 容許開發路線可以分道揚鑣，也可以殊途同歸，兩條開發線路的結合點我們叫“合并”（merge）。表示合并的交付就等於有一個以上的父交付了，每個父交付表示每個開發線路發展到這裡的最貼近的交付。

The best way to see how this works is using the gitk(1) command; running gitk now on a git repository and looking for merge commits will help understand how the git organizes history.

最好的查看這個機制的方法是用 gitk(1) 命令；現在在版本庫中運行 gitk 命令，並查看一下那些合并交付會對你理解 git 是如何組織曆史的很有協助。

In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y. Equivalently, you could say that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X.

接著，我們說 交付X 對於 交付Y 來說是“可及的”， 如果 交付X 是 交付Y 的祖先的話。同樣地，你可以說 Y 是 X 的一個後裔， 或者說存在一個從 Y 追索到 X 的世系族譜。

  Understanding history: History diagrams 曆史沿革示圖

We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with lines drawn with - / and /. Time goes left to right:

某些時候，我們會用下面的示圖來描述 git 的曆史。所有的交付用 "o" 表示， 聯絡他們各個發展線路之間畫上 / 和 /。時間的推移是由左至右。

 

         o--o--o <-- Branch A        / o--o--o <-- master        /         o--o--o <-- Branch B

If we need to talk about a particular commit, the character "o" may be replaced with another letter or number.

如果需要具體地談論某個交付，那麼就用其他的字母或者是數字來替代 "o" 。

  Understanding history: What is a branch? 理解曆史：什麼是分支

When we need to be precise, we will use the word "branch" to mean a line of development, and "branch head" (or just "head") to mean a reference to the most recent commit on a branch. In the example above, the branch head named "A" is a pointer to one particular commit, but we refer to the line of three commits leading up to that point as all being part of "branch A".

為 準確起見，我們用 “分支” 這個詞來表達開發的線路， 並且用 “分支頭”（或者是 “頭”）來表達一個分支中最新的交付。在上面的例子中，那個叫 “A” 的分支頭是一個指向一個具體的交付的指標。但是我們指出，該線路上發展到這個點的三個交付全都是 “分支A” 的組成部分。

However, when no confusion will result, we often just use the term "branch" both for branches and for branch heads.

不過， 在不至於產生混淆的前提下，我們常常只是用 “分支” 這個術語來表示分支和分支頭。

  Manipulating branches 操作分支

Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands:

建立，刪除，和更改分支都是很快而容易的；這裡是這個命令的摘要：

git branch list all branches 列舉所有的分支

git branch <branch>

create a new branch named <branch>, referencing the same point in history as the current branch 建立一個新的分支，並引用當前分支作為同一曆史沿革

git branch <branch> <start-point>

create a new branch named <branch>, referencing <start-point>, which may be specified any way you like, including using a branch name or a tag name

建立一個名叫 <branch> 的新分支，引用 <start-point>，它是可以任意指定的，可以是現存的分支的名稱或者是標籤的名稱

git branch -d <branch>

delete the branch <branch>; if the branch you are deleting points to a commit which is not reachable from the current branch, this command will fail with a warning.

刪除一個叫 <branch> 的分支；如果你要刪除的這個分支所指向的當前分支中一個不可及的交付的話，那麼命令將返回失敗並作出提示

git branch -D <branch> even if the branch points to a commit not reachable from the current branch, you may know that that commit is still reachable from some other branch or tag. In that case it is safe to use this command to force git to delete the branch. 儘管需要刪除一個當前分支不可及的交付，但是你知道那個交付仍然可有其他的分支或者是標籤可及。在這種情況下，用這個命令強制移除一個分支是安全的。

git checkout <branch>

make the current branch <branch>, updating the working directory to reflect the version referenced by <branch>

提取分支，也即是引用 <branch> 版本狀態更新工作目錄的內容

git checkout -b <new> <start-point>

create a new branch <new> referencing <start-point>, and check it out.

引用 <start-point> 建立一個叫 <new> 的分支，並且將它提取出來。

The special symbol "HEAD" can always be used to refer to the current branch. In fact, git uses a file named "HEAD" in the .git directory to remember which branch is current:

特殊的標號 "HEAD" 總是被用作引用，指向當前分支。事實上，git 是用 .git 目錄中的名叫 "HEAD" 的檔案來記住那個是當前分支。

 

$ cat .git/HEADref: refs/heads/master

  Examining an old version without creating a new branch 不通過建立新分支來調查舊版本

The git-checkout command normally expects a branch head, but will also accept an arbitrary commit; for example, you can check out the commit referenced by a tag:

git-checkout 命令按常規是抽取分支頭的，但是也可以接受任意的交付；例如，你可以引用一個標籤來進行提取。

 

$ git checkout v2.6.17Note: moving to "v2.6.17" which isn't a local branchIf you want to create a new branch from this checkout, you may do so(now or later) by using -b with the checkout command again. Example:  git checkout -b <new_branch_name>HEAD is now at 427abfa... Linux v2.6.17

The HEAD then refers to the SHA1 of the commit instead of to a branch, and git branch shows that you are no longer on a branch:

此時，HEAD 將指向交付的 SHA1 來代替分支名稱， git branch 命令表明你現在的項目狀態不從屬於任何一個分支：

 

$ cat .git/HEAD427abfa28afedffadfca9dd8b067eb6d36bac53f$ git branch* (no branch)  master

In this case we say that the HEA