Git User Manual
===============
Git is a fast distributed revision control system.
This manual is designed to be readable by someone with basic UNIX
command-line skills, but no previous knowledge of Git.
<<repositories-and-branches>> and <<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.
People needing to do actual development will also want to read
<<Developing-With-git>> and <<sharing-development>>.
Further chapters cover more specialized topics.
Comprehensive reference documentation is available through the man
pages, or linkgit:git-help[1] command. For example, for the command
`git clone <repo>`, you can either use:
------------------------------------------------
$ man git-clone
------------------------------------------------
or:
------------------------------------------------
$ git help clone
------------------------------------------------
With the latter, you can use the manual viewer of your choice; see
linkgit:git-help[1] for more information.
See also <<git-quick-start>> for a brief overview of Git commands,
without any explanation.
Finally, see <<todo>> for ways that you can help make this manual more
complete.
[[repositories-and-branches]]
Repositories and Branches
=========================
[[how-to-get-a-git-repository]]
How to get a Git repository
---------------------------
It will be useful to have a Git repository to experiment with as you
read this manual.
The best way to get one is by using the linkgit: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 itself (approx. 40MB download):
$ git clone git://git.kernel.org/pub/scm/git/git.git
# the Linux kernel (approx. 640MB download):
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.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` in the examples above). After you cd into this
directory, you will see that it contains a copy of the project files,
called the <<def_working_tree,working tree>>, together with a special
top-level directory named `.git`, which contains all the information
about the history of the project.
[[how-to-check-out]]
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 <<def_commit,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 <<def_branch,branches>>, which may
merge and diverge.
A single Git repository can track development on multiple branches. It
does this by keeping a list of <<def_head,heads>> which reference the
latest commit on each branch; the linkgit:git-branch[1] command shows
you the list of branch heads:
------------------------------------------------
$ 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.
Most projects also use <<def_tag,tags>>. Tags, like heads, are
references into the project's history, and can be listed using the
linkgit:git-tag[1] command:
------------------------------------------------
$ git tag -l
v2.6.11
v2.6.11-tree
v2.6.12
v2.6.12-rc2
v2.6.12-rc3
v2.6.12-rc4
v2.6.12-rc5
v2.6.12-rc6
v2.6.13
...
------------------------------------------------
Tags are expected to always point at the same version of a project,
while heads are expected to advance as development progresses.
Create a new branch head pointing to one of these versions and check it
out using linkgit: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 linkgit:git-branch[1] shows two
branches, with an asterisk marking the currently checked-out branch:
------------------------------------------------
$ 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
------------------------------------------------
$ 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.
[[understanding-commits]]
Understanding History: Commits
------------------------------
Every change in the history of a project is represented by a commit.
The linkgit:git-show[1] command shows the most recent commit on the
current branch:
------------------------------------------------
$ git show
commit 17cf781661e6d38f737f15f53ab552f1e95960d7
Author: 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.c
index 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
"SHA-1 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.
In fact, in <<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.
[[understanding-reachability]]
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.
The best way to see how this works is using the linkgit:gitk[1]
command; running gitk now on a Git repository and looking for merge
commits will help unders