-Git User's Manual
-_________________
+Git User's Manual (for version 1.5.1 or newer)
+______________________________________________
+
+
+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.
-Chapter 1 gives a brief overview of git commands, without any
-explanation; you may prefer to skip to chapter 2 on a first reading.
+<<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.
-Chapters 2 and 3 explain how to fetch and study a project using
-git--the tools you'd need to build and test a particular version of a
-software project, to search for regressions, and so on.
-
-Chapter 4 explains how to do development with git, and chapter 5 how
-to share that development with others.
+People needing to do actual development will also want to read
+<<Developing-with-git>> and <<sharing-development>>.
Further chapters cover more specialized topics.
$ man git-clone
------------------------------------------------
-Git Quick Start
-===============
-
-This is a quick summary of the major commands; the following chapters
-will explain how these work in more detail.
-
-Creating a new repository
--------------------------
-
-From a tarball:
-
------------------------------------------------
-$ tar xzf project.tar.gz
-$ cd project
-$ git init
-Initialized empty Git repository in .git/
-$ git add .
-$ git commit
------------------------------------------------
-
-From a remote repository:
-
------------------------------------------------
-$ git clone git://example.com/pub/project.git
-$ cd project
------------------------------------------------
-
-Managing branches
------------------
-
------------------------------------------------
-$ git branch # list all branches in this repo
-$ git checkout test # switch working directory to branch "test"
-$ git branch new # create branch "new" starting at current HEAD
-$ git branch -d new # delete branch "new"
------------------------------------------------
-
-Instead of basing new branch on current HEAD (the default), use:
-
------------------------------------------------
-$ git branch new test # branch named "test"
-$ git branch new v2.6.15 # tag named v2.6.15
-$ git branch new HEAD^ # commit before the most recent
-$ git branch new HEAD^^ # commit before that
-$ git branch new test~10 # ten commits before tip of branch "test"
------------------------------------------------
-
-Create and switch to a new branch at the same time:
-
------------------------------------------------
-$ git checkout -b new v2.6.15
------------------------------------------------
-
-Update and examine branches from the repository you cloned from:
-
------------------------------------------------
-$ git fetch # update
-$ git branch -r # list
- origin/master
- origin/next
- ...
-$ git checkout -b masterwork origin/master
------------------------------------------------
-
-Fetch a branch from a different repository, and give it a new
-name in your repository:
-
------------------------------------------------
-$ git fetch git://example.com/project.git theirbranch:mybranch
-$ git fetch git://example.com/project.git v2.6.15:mybranch
------------------------------------------------
-
-Keep a list of repositories you work with regularly:
-
------------------------------------------------
-$ git remote add example git://example.com/project.git
-$ git remote # list remote repositories
-example
-origin
-$ git remote show example # get details
-* remote example
- URL: git://example.com/project.git
- Tracked remote branches
- master next ...
-$ git fetch example # update branches from example
-$ git branch -r # list all remote branches
------------------------------------------------
-
-
-Exploring history
------------------
-
------------------------------------------------
-$ gitk # visualize and browse history
-$ git log # list all commits
-$ git log src/ # ...modifying src/
-$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
-$ git log master..test # ...in branch test, not in branch master
-$ git log test..master # ...in branch master, but not in test
-$ git log test...master # ...in one branch, not in both
-$ git log -S'foo()' # ...where difference contain "foo()"
-$ git log --since="2 weeks ago"
-$ git log -p # show patches as well
-$ git show # most recent commit
-$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
-$ git diff v2.6.15..HEAD # diff with current head
-$ git grep "foo()" # search working directory for "foo()"
-$ git grep v2.6.15 "foo()" # search old tree for "foo()"
-$ git show v2.6.15:a.txt # look at old version of a.txt
------------------------------------------------
-
-Search for regressions:
-
------------------------------------------------
-$ git bisect start
-$ git bisect bad # current version is bad
-$ git bisect good v2.6.13-rc2 # last known good revision
-Bisecting: 675 revisions left to test after this
- # test here, then:
-$ git bisect good # if this revision is good, or
-$ git bisect bad # if this revision is bad.
- # repeat until done.
------------------------------------------------
-
-Making changes
---------------
-
-Make sure git knows who to blame:
-
-------------------------------------------------
-$ cat >~/.gitconfig <<\EOF
-[user]
- name = Your Name Comes Here
- email = you@yourdomain.example.com
-EOF
-------------------------------------------------
-
-Select file contents to include in the next commit, then make the
-commit:
-
------------------------------------------------
-$ git add a.txt # updated file
-$ git add b.txt # new file
-$ git rm c.txt # old file
-$ git commit
------------------------------------------------
-
-Or, prepare and create the commit in one step:
-
------------------------------------------------
-$ git commit d.txt # use latest content only of d.txt
-$ git commit -a # use latest content of all tracked files
------------------------------------------------
-
-Merging
--------
-
------------------------------------------------
-$ git merge test # merge branch "test" into the current branch
-$ git pull git://example.com/project.git master
- # fetch and merge in remote branch
-$ git pull . test # equivalent to git merge test
------------------------------------------------
-
-Sharing your changes
---------------------
-
-Importing or exporting patches:
-
------------------------------------------------
-$ git format-patch origin..HEAD # format a patch for each commit
- # in HEAD but not in origin
-$ git am mbox # import patches from the mailbox "mbox"
------------------------------------------------
-
-Fetch a branch in a different git repository, then merge into the
-current branch:
-
------------------------------------------------
-$ git pull git://example.com/project.git theirbranch
------------------------------------------------
-
-Store the fetched branch into a local branch before merging into the
-current branch:
-
------------------------------------------------
-$ git pull git://example.com/project.git theirbranch:mybranch
------------------------------------------------
-
-After creating commits on a local branch, update the remote
-branch with your commits:
-
------------------------------------------------
-$ git push ssh://example.com/project.git mybranch:theirbranch
------------------------------------------------
-
-When remote and local branch are both named "test":
-
------------------------------------------------
-$ git push ssh://example.com/project.git test
------------------------------------------------
-
-Shortcut version for a frequently used remote repository:
-
------------------------------------------------
-$ git remote add example ssh://example.com/project.git
-$ git push example test
------------------------------------------------
-
-Repository maintenance
-----------------------
-
-Check for corruption:
-
------------------------------------------------
-$ git fsck
------------------------------------------------
+See also <<git-quick-start>> for a brief overview of git commands,
+without any explanation.
-Recompress, remove unused cruft:
+Also, see <<todo>> for ways that you can help make this manual more
+complete.
------------------------------------------------
-$ git gc
------------------------------------------------
+[[repositories-and-branches]]
Repositories and Branches
=========================
+[[how-to-get-a-git-repository]]
How to get a git repository
---------------------------
In most of the following, examples will be taken from one of the two
repositories above.
+[[how-to-check-out]]
How to check out a different version of a project
-------------------------------------------------
* master
------------------------------------------------
-A freshly cloned repository contains a single branch head, named
-"master", and working directory is initialized to the state of
-the project referred to by "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
with no way to find the history it used to point to; so use this command
carefully.
+[[understanding-commits]]
Understanding History: Commits
------------------------------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
that Y is a descendent of X, or that there is a chain of parents
leading from commit Y to commit X.
+[[history-diagrams]]
Understanding history: History diagrams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If we need to talk about a particular commit, the character "o" may
be replaced with another letter or number.
+[[what-is-a-branch]]
Understanding history: What is a branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
However, when no confusion will result, we often just use the term
"branch" both for branches and for branch heads.
+[[manipulating-branches]]
Manipulating branches
---------------------
including using a branch name or a tag name
git branch -d <branch>::
delete the branch <branch>; if the branch you are deleting
- points to a commit which is not reachable from this branch,
- this command will fail with a warning.
+ points to a commit which is not reachable from the current
+ branch, this command will fail with a warning.
git branch -D <branch>::
even if the branch points to a commit not reachable
from the current branch, you may know that that commit
create a new branch <new> referencing <start-point>, and
check it out.
-It is also useful to know that the special symbol "HEAD" can always
-be used to refer to the current branch.
+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:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+[[detached-head]]
+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 v2.6.17
+Note: moving to "v2.6.17" which isn't a local branch
+If 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:
+
+------------------------------------------------
+$ cat .git/HEAD
+427abfa28afedffadfca9dd8b067eb6d36bac53f
+$ git branch
+* (no branch)
+ master
+------------------------------------------------
+
+In this case we say that the HEAD is "detached".
+
+This is an easy way to check out a particular version without having to
+make up a name for the new branch. You can still create a new branch
+(or tag) for this version later if you decide to.
+
+[[examining-remote-branches]]
Examining branches from a remote repository
-------------------------------------------
The full name is occasionally useful if, for example, there ever
exists a tag and a branch with the same name.
-As another useful shortcut, if the repository "origin" posesses only
-a single branch, you can refer to that branch as just "origin".
-
-More generally, if you have defined a remote repository named
-"example", you can refer to the branch in that repository as
-"example". And for a repository with multiple branches, this will
-refer to the branch designated as the "HEAD" branch.
+As another useful shortcut, the "HEAD" of a repository can be referred
+to just using the name of that repository. So, for example, "origin"
+is usually a shortcut for the HEAD branch in the repository "origin".
For the complete list of paths which git checks for references, and
the order it uses to decide which to choose when there are multiple
repository. It will not touch any of your own branches--not even the
"master" branch that was created for you on clone.
+[[fetching-branches]]
Fetching branches from other repositories
-----------------------------------------
text editor. (See the "CONFIGURATION FILE" section of
gitlink:git-config[1] for details.)
+[[exploring-git-history]]
Exploring git history
=====================
We start with one specialized tool that is useful for finding the
commit that introduced a bug into a project.
+[[using-bisect]]
How to use bisect to find a regression
--------------------------------------
then test, run "bisect good" or "bisect bad" as appropriate, and
continue.
+[[naming-commits]]
Naming commits
--------------
e05db0fd4f31dde7005f075a84f96b360d05984b
-------------------------------------------------
+[[creating-tags]]
Creating tags
-------------
You can use stable-1 to refer to the commit 1b2e1d63ff.
-This creates a "lightweight" tag. If the tag is a tag you wish to
-share with others, and possibly sign cryptographically, then you
-should create a tag object instead; see the gitlink:git-tag[1] man
-page for details.
+This creates a "lightweight" tag. If you would also like to include a
+comment with the tag, and possibly sign it cryptographically, then you
+should create a tag object instead; see the gitlink:git-tag[1] man page
+for details.
+[[browsing-revisions]]
Browsing revisions
------------------
multiple independent lines of development, the particular order that
commits are listed in may be somewhat arbitrary.
+[[generating-diffs]]
Generating diffs
----------------
not reachable from test, then the combined result of these patches
will not be the same as the diff produced by the git-diff example.
+[[viewing-old-file-versions]]
Viewing old file versions
-------------------------
Before the colon may be anything that names a commit, and after it
may be any path to a file tracked by git.
+[[history-examples]]
Examples
--------
+[[counting-commits-on-a-branch]]
+Counting the number of commits on a branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose you want to know how many commits you've made on "mybranch"
+since it diverged from "origin":
+
+-------------------------------------------------
+$ git log --pretty=oneline origin..mybranch | wc -l
+-------------------------------------------------
+
+Alternatively, you may often see this sort of thing done with the
+lower-level command gitlink:git-rev-list[1], which just lists the SHA1's
+of all the given commits:
+
+-------------------------------------------------
+$ git rev-list origin..mybranch | wc -l
+-------------------------------------------------
+
+[[checking-for-equal-branches]]
Check whether two branches point at the same history
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
will return no commits when the two branches are equal.
+[[finding-tagged-descendants]]
Find first tagged version including a given fix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and
from v1.5.0-rc2, but not from v1.5.0-rc0.
+[[showing-commits-unique-to-a-branch]]
+Showing commits unique to a given branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Developing with git
-===================
+Suppose you would like to see all the commits reachable from the branch
+head named "master" but not from any other head in your repository.
-Telling git your name
----------------------
+We can list all the heads in this repository with
+gitlink:git-show-ref[1]:
-Before creating any commits, you should introduce yourself to git. The
-easiest way to do so is:
+-------------------------------------------------
+$ git show-ref --heads
+bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
+db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
+a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
+24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
+1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
+-------------------------------------------------
-------------------------------------------------
-$ cat >~/.gitconfig <<\EOF
-[user]
+We can get just the branch-head names, and remove "master", with
+the help of the standard utilities cut and grep:
+
+-------------------------------------------------
+$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
+refs/heads/core-tutorial
+refs/heads/maint
+refs/heads/tutorial-2
+refs/heads/tutorial-fixes
+-------------------------------------------------
+
+And then we can ask to see all the commits reachable from master
+but not from these other heads:
+
+-------------------------------------------------
+$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
+ grep -v '^refs/heads/master' )
+-------------------------------------------------
+
+Obviously, endless variations are possible; for example, to see all
+commits reachable from some head but not from any tag in the repository:
+
+-------------------------------------------------
+$ gitk ($ git show-ref --heads ) --not $( git show-ref --tags )
+-------------------------------------------------
+
+(See gitlink:git-rev-parse[1] for explanations of commit-selecting
+syntax such as `--not`.)
+
+[[making-a-release]]
+Creating a changelog and tarball for a software release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The gitlink:git-archive[1] command can create a tar or zip archive from
+any version of a project; for example:
+
+-------------------------------------------------
+$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+-------------------------------------------------
+
+will use HEAD to produce a tar archive in which each filename is
+preceded by "prefix/".
+
+If you're releasing a new version of a software project, you may want
+to simultaneously make a changelog to include in the release
+announcement.
+
+Linus Torvalds, for example, makes new kernel releases by tagging them,
+then running:
+
+-------------------------------------------------
+$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
+-------------------------------------------------
+
+where release-script is a shell script that looks like:
+
+-------------------------------------------------
+#!/bin/sh
+stable="$1"
+last="$2"
+new="$3"
+echo "# git tag v$new"
+echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
+echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
+echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
+echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
+echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
+-------------------------------------------------
+
+and then he just cut-and-pastes the output commands after verifying that
+they look OK.
+
+Finding commits referencing a file with given content
+-----------------------------------------------------
+
+Somebody hands you a copy of a file, and asks which commits modified a
+file such that it contained the given content either before or after the
+commit. You can find out with this:
+
+-------------------------------------------------
+$ git log --raw -r --abbrev=40 --pretty=oneline -- filename |
+ grep -B 1 `git hash-object filename`
+-------------------------------------------------
+
+Figuring out why this works is left as an exercise to the (advanced)
+student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and
+gitlink:git-hash-object[1] man pages may prove helpful.
+
+[[Developing-with-git]]
+Developing with git
+===================
+
+[[telling-git-your-name]]
+Telling git your name
+---------------------
+
+Before creating any commits, you should introduce yourself to git. The
+easiest way to do so is to make sure the following lines appear in a
+file named .gitconfig in your home directory:
+
+------------------------------------------------
+[user]
name = Your Name Comes Here
email = you@yourdomain.example.com
-EOF
------------------------------------------------
(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for
details on the configuration file.)
+[[creating-a-new-repository]]
Creating a new repository
-------------------------
-------------------------------------------------
[[how-to-make-a-commit]]
-how to make a commit
+How to make a commit
--------------------
Creating a new commit takes three steps:
$ git diff # difference between the index file and your
# working directory; changes that would not
# be included if you ran "commit" now.
+$ git diff HEAD # difference between HEAD and working tree; what
+ # would be committed if you ran "commit -a" now.
$ git status # a brief per-file summary of the above.
-------------------------------------------------
-creating good commit messages
+[[creating-good-commit-messages]]
+Creating good commit messages
-----------------------------
Though not required, it's a good idea to begin the commit message
the first line on the Subject line and the rest of the commit in the
body.
-how to merge
+[[ignoring-files]]
+Ignoring files
+--------------
+
+A project will often generate files that you do 'not' want to track with git.
+This typically includes files generated by a build process or temporary
+backup files made by your editor. Of course, 'not' tracking files with git
+is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
+annoying to have these untracked files lying around; e.g. they make
+"`git add .`" and "`git commit -a`" practically useless, and they keep
+showing up in the output of "`git status`", etc.
+
+Git therefore provides "exclude patterns" for telling git which files to
+actively ignore. Exclude patterns are thoroughly explained in the
+"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
+but the heart of the concept is simply a list of files which git should
+ignore. Entries in the list may contain globs to specify multiple files,
+or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
+excluded (ignored) file (i.e. later exclude patterns override earlier ones).
+The following example should illustrate such patterns:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]
+-------------------------------------------------
+
+The next question is where to put these exclude patterns so that git can
+find them. Git looks for exclude patterns in the following files:
+
+`.gitignore` files in your working tree:::
+ You may store multiple `.gitignore` files at various locations in your
+ working tree. Each `.gitignore` file is applied to the directory where
+ it's located, including its subdirectories. Furthermore, the
+ `.gitignore` files can be tracked like any other files in your working
+ tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
+ therefore the right place to put exclude patterns that are meant to
+ be shared between all project participants, such as build output files
+ (e.g. `\*.o`), etc.
+`.git/info/exclude` in your repo:::
+ Exclude patterns in this file are applied to the working tree as a
+ whole. Since the file is not located in your working tree, it does
+ not follow push/pull/clone like `.gitignore` can do. This is therefore
+ the place to put exclude patterns that are local to your copy of the
+ repo (i.e. 'not' shared between project participants), such as
+ temporary backup files made by your editor (e.g. `\*~`), etc.
+The file specified by the `core.excludesfile` config directive:::
+ By setting the `core.excludesfile` config directive you can tell git
+ where to find more exclude patterns (see gitlink:git-config[1] for
+ more information on configuration options). This config directive
+ can be set in the per-repo `.git/config` file, in which case the
+ exclude patterns will apply to that repo only. Alternatively, you
+ can set the directive in the global `~/.gitconfig` file to apply
+ the exclude pattern to all your git repos. As with the above
+ `.git/info/exclude` (and, indeed, with git config directives in
+ general), this directive does not follow push/pull/clone, but remain
+ local to your repo(s).
+
+[NOTE]
+In addition to the above alternatives, there are git commands that can take
+exclude patterns directly on the command line. See gitlink:git-ls-files[1]
+for an example of this.
+
+[[how-to-merge]]
+How to merge
------------
You can rejoin two diverging branches of development using
has two parents, one pointing to the top of the current branch, and
one to the top of the other branch.
-In more detail:
-
[[resolving-a-merge]]
Resolving a merge
-----------------
The above is all you need to know to resolve a simple merge. But git
also provides more information to help resolve conflicts:
+[[conflict-resolution]]
Getting conflict-resolution help during a merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These will display all commits which exist only on HEAD or on
MERGE_HEAD, and which touch an unmerged file.
+You may also use gitlink:git-mergetool[1], which lets you merge the
+unmerged files using external tools such as emacs or kdiff3.
+
Each time you resolve the conflicts in a file and update the index:
-------------------------------------------------
git-diff will (by default) no longer show diffs for that file.
[[undoing-a-merge]]
-undoing a merge
+Undoing a merge
---------------
If you get stuck and decide to just give up and throw the whole mess
itself have been merged into another branch, as doing so may confuse
further merges.
+[[fast-forwards]]
Fast-forward merges
-------------------
parents, one pointing at each of the two lines of development that
were merged.
-However, if one of the two lines of development is completely
-contained within the other--so every commit present in the one is
-already contained in the other--then git just performs a
-<<fast-forwards,fast forward>>; the head of the current branch is
-moved forward to point at the head of the merged-in branch, without
-any new commits being created.
+However, if the current branch is a descendant of the other--so every
+commit present in the one is already contained in the other--then git
+just performs a "fast forward"; the head of the current branch is moved
+forward to point at the head of the merged-in branch, without any new
+commits being created.
+[[fixing-mistakes]]
Fixing mistakes
---------------
change, and cannot correctly perform repeated merges from
a branch that has had its history changed.
+[[reverting-a-commit]]
Fixing a mistake with a new commit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
this is an advanced topic to be left for
<<cleaning-up-history,another chapter>>.
+[[checkout-of-path]]
Checking out an old version of a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
which will display the given version of the file.
+[[ensuring-good-performance]]
Ensuring good performance
-------------------------
to recompress the archive. This can be very time-consuming, so
you may prefer to run git-gc when you are not doing other work.
+
+[[ensuring-reliability]]
Ensuring reliability
--------------------
+[[checking-for-corruption]]
Checking the repository for corruption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...
-------------------------------------------------
-Dangling objects are objects that are harmless, but also unnecessary;
-you can remove them at any time with gitlink:git-prune[1] or the --prune
+Dangling objects are not a problem. At worst they may take up a little
+extra disk space. They can sometimes provide a last-resort method of
+recovery lost work--see <<dangling-objects>> for details. However, if
+you want, you may remove them with gitlink:git-prune[1] or the --prune
option to gitlink:git-gc[1]:
-------------------------------------------------
git-gc when run without any options), it is not safe to prune while
other git operations are in progress in the same repository.
-For more about dangling objects, see <<dangling-objects>>.
-
-
+[[recovering-lost-changes]]
Recovering lost changes
~~~~~~~~~~~~~~~~~~~~~~~
+[[reflogs]]
Reflogs
^^^^^^^
$ git show master@{3} # 3, ... changes ago.
$ gitk master@{yesterday} # See where it pointed yesterday,
$ gitk master@{"1 week ago"} # ... or last week
+$ git log --walk-reflogs master # show reflog entries for master
-------------------------------------------------
+A separate reflog is kept for the HEAD, so
+
+-------------------------------------------------
+$ git show HEAD@{"1 week ago"}
+-------------------------------------------------
+
+will show what HEAD pointed to one week ago, not what the current branch
+pointed to one week ago. This allows you to see the history of what
+you've checked out.
+
The reflogs are kept by default for 30 days, after which they may be
pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
how to control this pruning, and see the "SPECIFYING REVISIONS"
same project, the reflog history is not shared: it tells you only about
how the branches in your local repository have changed over time.
+[[dangling-object-recovery]]
Examining dangling objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
-In some situations the reflog may not be able to save you. For
-example, suppose you delete a branch, then realize you need the history
-it contained. The reflog is also deleted; however, if you have not
-yet pruned the repository, then you may still be able to find
-the lost commits; run git-fsck and watch for output that mentions
-"dangling commits":
+In some situations the reflog may not be able to save you. For example,
+suppose you delete a branch, then realize you need the history it
+contained. The reflog is also deleted; however, if you have not yet
+pruned the repository, then you may still be able to find the lost
+commits in the dangling objects that git-fsck reports. See
+<<dangling-objects>> for the details.
-------------------------------------------------
$ git fsck
$ git branch recovered-branch 7281251ddd
------------------------------------------------
+Other types of dangling objects (blobs and trees) are also possible, and
+dangling objects can arise in other situations.
+
+[[sharing-development]]
Sharing development with others
===============================
$ git pull
-------------------------------------------------
-See the descriptions of the branch.<name>.remote and
-branch.<name>.merge options in gitlink:git-config[1] to learn
-how to control these defaults depending on the current branch.
+See the descriptions of the branch.<name>.remote and branch.<name>.merge
+options in gitlink:git-config[1] to learn how to control these defaults
+depending on the current branch. Also note that the --track option to
+gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to
+automatically set the default remote branch to pull from at the time
+that a branch is created:
+
+-------------------------------------------------
+$ git checkout --track -b origin/maint maint
+-------------------------------------------------
In addition to saving you keystrokes, "git pull" also helps you by
producing a default commit message documenting the branch and
are roughly equivalent. The former is actually very commonly used.
+[[submitting-patches]]
Submitting patches to a project
-------------------------------
Consult the mailing list for your project first to determine how they
prefer such patches be handled.
+[[importing-patches]]
Importing patches to a project
------------------------------
the original mailbox, with authorship and commit log message each
taken from the message containing each patch.
-[[setting-up-a-public-repository]]
-Setting up a public repository
-------------------------------
+[[public-repositories]]
+Public git repositories
+-----------------------
-Another way to submit changes to a project is to simply tell the
-maintainer of that project to pull from your repository, exactly as
-you did in the section "<<getting-updates-with-git-pull, Getting
-updates with git pull>>".
+Another way to submit changes to a project is to tell the maintainer of
+that project to pull the changes from your repository using git-pull[1].
+In the section "<<getting-updates-with-git-pull, Getting updates with
+git pull>>" we described this as a way to get updates from the "main"
+repository, but it works just as well in the other direction.
-If you and maintainer both have accounts on the same machine, then
-then you can just pull changes from each other's repositories
-directly; note that all of the commands (gitlink:git-clone[1],
-git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
-will also accept a local directory name; so, for example, you can
-use
+If you and the maintainer both have accounts on the same machine, then
+you can just pull changes from each other's repositories directly;
+commands that accepts repository URLs as arguments will also accept a
+local directory name:
-------------------------------------------------
$ git clone /path/to/repository
$ git pull /path/to/other/repository
-------------------------------------------------
-If this sort of setup is inconvenient or impossible, another (more
-common) option is to set up a public repository on a public server.
-This also allows you to cleanly separate private work in progress
-from publicly visible work.
+However, the more common way to do this is to maintain a separate public
+repository (usually on a different host) for others to pull changes
+from. This is usually more convenient, and allows you to cleanly
+separate private work in progress from publicly visible work.
You will continue to do your day-to-day work in your personal
repository, but periodically "push" changes from your personal
| they push V
their public repo <------------------- their repo
-Now, assume your personal repository is in the directory ~/proj. We
-first create a new clone of the repository:
+[[setting-up-a-public-repository]]
+Setting up a public repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Assume your personal repository is in the directory ~/proj. We
+first create a new clone of the repository and tell git-daemon that it
+is meant to be public:
-------------------------------------------------
-$ git clone --bare proj-clone.git
+$ git clone --bare ~/proj proj.git
+$ touch proj.git/git-daemon-export-ok
-------------------------------------------------
-The resulting directory proj-clone.git will contains a "bare" git
-repository--it is just the contents of the ".git" directory, without
-a checked-out copy of a working directory.
+The resulting directory proj.git contains a "bare" git repository--it is
+just the contents of the ".git" directory, without any files checked out
+around it.
-Next, copy proj-clone.git to the server where you plan to host the
+Next, copy proj.git to the server where you plan to host the
public repository. You can use scp, rsync, or whatever is most
convenient.
-If somebody else maintains the public server, they may already have
-set up a git service for you, and you may skip to the section
+[[exporting-via-git]]
+Exporting a git repository via the git protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the preferred method.
+
+If someone else administers the server, they should tell you what
+directory to put the repository in, and what git:// url it will appear
+at. You can then skip to the section
"<<pushing-changes-to-a-public-repository,Pushing changes to a public
repository>>", below.
-Otherwise, the following sections explain how to export your newly
-created public repository:
+Otherwise, all you need to do is start gitlink:git-daemon[1]; it will
+listen on port 9418. By default, it will allow access to any directory
+that looks like a git directory and contains the magic file
+git-daemon-export-ok. Passing some directory paths as git-daemon
+arguments will further restrict the exports to those paths.
+
+You can also run git-daemon as an inetd service; see the
+gitlink:git-daemon[1] man page for details. (See especially the
+examples section.)
[[exporting-via-http]]
Exporting a git repository via http
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The git protocol gives better performance and reliability, but on a
host with a web server set up, http exports may be simpler to set up.
-------------------------------------------------
$ mv proj.git /home/you/public_html/proj.git
$ cd proj.git
-$ git update-server-info
+$ git --bare update-server-info
$ chmod a+x hooks/post-update
-------------------------------------------------
(For an explanation of the last two lines, see
gitlink:git-update-server-info[1], and the documentation
-link:hooks.txt[Hooks used by git].)
+link:hooks.html[Hooks used by git].)
Advertise the url of proj.git. Anybody else should then be able to
clone or pull from that url, for example with a commandline like:
for a slightly more sophisticated setup using WebDAV which also
allows pushing over http.)
-[[exporting-via-git]]
-Exporting a git repository via the git protocol
------------------------------------------------
-
-This is the preferred method.
-
-For now, we refer you to the gitlink:git-daemon[1] man page for
-instructions. (See especially the examples section.)
-
[[pushing-changes-to-a-public-repository]]
Pushing changes to a public repository
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Note that the two techniques outline above (exporting via
+Note that the two techniques outlined above (exporting via
<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
maintainers to fetch your latest changes, but they do not allow write
access, which you will need to update the public repository with the
save typing; so, for example, after
-------------------------------------------------
-$ cat >.git/config <<EOF
+$ cat >>.git/config <<EOF
[remote "public-repo"]
url = ssh://yourserver.com/~you/proj.git
EOF
and remote.<name>.push options in gitlink:git-config[1] for
details.
+[[setting-up-a-shared-repository]]
Setting up a shared repository
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Another way to collaborate is by using a model similar to that
commonly used in CVS, where several developers with special rights
all push to and pull from a single shared repository. See
-link:cvs-migration.txt[git for CVS users] for instructions on how to
+link:cvs-migration.html[git for CVS users] for instructions on how to
set this up.
-Allow web browsing of a repository
-----------------------------------
+However, while there is nothing wrong with git's support for shared
+repositories, this mode of operation is not generally recommended,
+simply because the mode of collaboration that git supports--by
+exchanging patches and pulling from public repositories--has so many
+advantages over the central shared repository:
+
+ - Git's ability to quickly import and merge patches allows a
+ single maintainer to process incoming changes even at very
+ high rates. And when that becomes too much, git-pull provides
+ an easy way for that maintainer to delegate this job to other
+ maintainers while still allowing optional review of incoming
+ changes.
+ - Since every developer's repository has the same complete copy
+ of the project history, no repository is special, and it is
+ trivial for another developer to take over maintenance of a
+ project, either by mutual agreement, or because a maintainer
+ becomes unresponsive or difficult to work with.
+ - The lack of a central group of "committers" means there is
+ less need for formal decisions about who is "in" and who is
+ "out".
+
+[[setting-up-gitweb]]
+Allowing web browsing of a repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The gitweb cgi script provides users an easy way to browse your
project's files and history without having to install git; see the file
gitweb/INSTALL in the git source tree for instructions on setting it up.
+[[sharing-development-examples]]
Examples
--------
-TODO: topic branches, typical roles as in everyday.txt, ?
+[[maintaining-topic-branches]]
+Maintaining topic branches for a Linux subsystem maintainer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This describes how Tony Luck uses git in his role as maintainer of the
+IA64 architecture for the Linux kernel.
+
+He uses two public branches:
+
+ - A "test" tree into which patches are initially placed so that they
+ can get some exposure when integrated with other ongoing development.
+ This tree is available to Andrew for pulling into -mm whenever he
+ wants.
+
+ - A "release" tree into which tested patches are moved for final sanity
+ checking, and as a vehicle to send them upstream to Linus (by sending
+ him a "please pull" request.)
+
+He also uses a set of temporary branches ("topic branches"), each
+containing a logical grouping of patches.
+
+To set this up, first create your work tree by cloning Linus's public
+tree:
+
+-------------------------------------------------
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
+$ cd work
+-------------------------------------------------
+
+Linus's tree will be stored in the remote branch named origin/master,
+and can be updated using gitlink:git-fetch[1]; you can track other
+public trees using gitlink:git-remote[1] to set up a "remote" and
+git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>.
+
+Now create the branches in which you are going to work; these start out
+at the current tip of origin/master branch, and should be set up (using
+the --track option to gitlink:git-branch[1]) to merge changes in from
+Linus by default.
+
+-------------------------------------------------
+$ git branch --track test origin/master
+$ git branch --track release origin/master
+-------------------------------------------------
+
+These can be easily kept up to date using gitlink:git-pull[1]
+
+-------------------------------------------------
+$ git checkout test && git pull
+$ git checkout release && git pull
+-------------------------------------------------
+
+Important note! If you have any local changes in these branches, then
+this merge will create a commit object in the history (with no local
+changes git will simply do a "Fast forward" merge). Many people dislike
+the "noise" that this creates in the Linux history, so you should avoid
+doing this capriciously in the "release" branch, as these noisy commits
+will become part of the permanent history when you ask Linus to pull
+from the release branch.
+
+A few configuration variables (see gitlink:git-config[1]) can
+make it easy to push both branches to your public tree. (See
+<<setting-up-a-public-repository>>.)
+
+-------------------------------------------------
+$ cat >> .git/config <<EOF
+[remote "mytree"]
+ url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
+ push = release
+ push = test
+EOF
+-------------------------------------------------
+
+Then you can push both the test and release trees using
+gitlink:git-push[1]:
+
+-------------------------------------------------
+$ git push mytree
+-------------------------------------------------
+
+or push just one of the test and release branches using:
+
+-------------------------------------------------
+$ git push mytree test
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git push mytree release
+-------------------------------------------------
+
+Now to apply some patches from the community. Think of a short
+snappy name for a branch to hold this patch (or related group of
+patches), and create a new branch from the current tip of Linus's
+branch:
+
+-------------------------------------------------
+$ git checkout -b speed-up-spinlocks origin
+-------------------------------------------------
+
+Now you apply the patch(es), run some tests, and commit the change(s). If
+the patch is a multi-part series, then you should apply each as a separate
+commit to this branch.
+
+-------------------------------------------------
+$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
+-------------------------------------------------
+
+When you are happy with the state of this change, you can pull it into the
+"test" branch in preparation to make it public:
+
+-------------------------------------------------
+$ git checkout test && git pull . speed-up-spinlocks
+-------------------------------------------------
+
+It is unlikely that you would have any conflicts here ... but you might if you
+spent a while on this step and had also pulled new versions from upstream.
+
+Some time later when enough time has passed and testing done, you can pull the
+same branch into the "release" tree ready to go upstream. This is where you
+see the value of keeping each patch (or patch series) in its own branch. It
+means that the patches can be moved into the "release" tree in any order.
+
+-------------------------------------------------
+$ git checkout release && git pull . speed-up-spinlocks
+-------------------------------------------------
+
+After a while, you will have a number of branches, and despite the
+well chosen names you picked for each of them, you may forget what
+they are for, or what status they are in. To get a reminder of what
+changes are in a specific branch, use:
+
+-------------------------------------------------
+$ git log linux..branchname | git-shortlog
+-------------------------------------------------
+
+To see whether it has already been merged into the test or release branches
+use:
+
+-------------------------------------------------
+$ git log test..branchname
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git log release..branchname
+-------------------------------------------------
+
+(If this branch has not yet been merged you will see some log entries.
+If it has been merged, then there will be no output.)
+
+Once a patch completes the great cycle (moving from test to release,
+then pulled by Linus, and finally coming back into your local
+"origin/master" branch) the branch for this change is no longer needed.
+You detect this when the output from:
+
+-------------------------------------------------
+$ git log origin..branchname
+-------------------------------------------------
+
+is empty. At this point the branch can be deleted:
+
+-------------------------------------------------
+$ git branch -d branchname
+-------------------------------------------------
+
+Some changes are so trivial that it is not necessary to create a separate
+branch and then merge into each of the test and release branches. For
+these changes, just apply directly to the "release" branch, and then
+merge that into the "test" branch.
+
+To create diffstat and shortlog summaries of changes to include in a "please
+pull" request to Linus you can use:
+
+-------------------------------------------------
+$ git diff --stat origin..release
+-------------------------------------------------
+
+and
+
+-------------------------------------------------
+$ git log -p origin..release | git shortlog
+-------------------------------------------------
+
+Here are some of the scripts that simplify all this even further.
+
+-------------------------------------------------
+==== update script ====
+# Update a branch in my GIT tree. If the branch to be updated
+# is origin, then pull from kernel.org. Otherwise merge
+# origin/master branch into test|release branch
+
+case "$1" in
+test|release)
+ git checkout $1 && git pull . origin
+ ;;
+origin)
+ before=$(cat .git/refs/remotes/origin/master)
+ git fetch origin
+ after=$(cat .git/refs/remotes/origin/master)
+ if [ $before != $after ]
+ then
+ git log $before..$after | git shortlog
+ fi
+ ;;
+*)
+ echo "Usage: $0 origin|test|release" 1>&2
+ exit 1
+ ;;
+esac
+-------------------------------------------------
+
+-------------------------------------------------
+==== merge script ====
+# Merge a branch into either the test or release branch
+
+pname=$0
+
+usage()
+{
+ echo "Usage: $pname branch test|release" 1>&2
+ exit 1
+}
+
+if [ ! -f .git/refs/heads/"$1" ]
+then
+ echo "Can't see branch <$1>" 1>&2
+ usage
+fi
+
+case "$2" in
+test|release)
+ if [ $(git log $2..$1 | wc -c) -eq 0 ]
+ then
+ echo $1 already merged into $2 1>&2
+ exit 1
+ fi
+ git checkout $2 && git pull . $1
+ ;;
+*)
+ usage
+ ;;
+esac
+-------------------------------------------------
+
+-------------------------------------------------
+==== status script ====
+# report on status of my ia64 GIT tree
+
+gb=$(tput setab 2)
+rb=$(tput setab 1)
+restore=$(tput setab 9)
+
+if [ `git rev-list test..release | wc -c` -gt 0 ]
+then
+ echo $rb Warning: commits in release that are not in test $restore
+ git log test..release
+fi
+
+for branch in `ls .git/refs/heads`
+do
+ if [ $branch = test -o $branch = release ]
+ then
+ continue
+ fi
+
+ echo -n $gb ======= $branch ====== $restore " "
+ status=
+ for ref in test release origin/master
+ do
+ if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
+ then
+ status=$status${ref:0:1}
+ fi
+ done
+ case $status in
+ trl)
+ echo $rb Need to pull into test $restore
+ ;;
+ rl)
+ echo "In test"
+ ;;
+ l)
+ echo "Waiting for linus"
+ ;;
+ "")
+ echo $rb All done $restore
+ ;;
+ *)
+ echo $rb "<$status>" $restore
+ ;;
+ esac
+ git log origin/master..$branch | git shortlog
+done
+-------------------------------------------------
[[cleaning-up-history]]
However, there is a situation in which it can be useful to violate this
assumption.
+[[patch-series]]
Creating the perfect patch series
---------------------------------
use them, and then explain some of the problems that can arise because
you are rewriting history.
+[[using-git-rebase]]
Keeping a patch series up to date using git-rebase
--------------------------------------------------
$ git rebase --abort
-------------------------------------------------
+[[modifying-one-commit]]
Modifying a single commit
-------------------------
(Either gitk or git-log may be useful for finding the commit.)
-Then check out a new branch at that commit, edit it, and rebase the rest of
-the series on top of it:
+Then check out that commit, edit it, and rebase the rest of the series
+on top of it (note that we could check out the commit on a temporary
+branch, but instead we're using a <<detached-head,detached head>>):
-------------------------------------------------
-$ git checkout -b TMP bad
+$ git checkout bad
$ # make changes here and update the index
$ git commit --amend
-$ git rebase --onto TMP bad mywork
+$ git rebase --onto HEAD bad mywork
-------------------------------------------------
-When you're done, you'll be left with mywork checked out, with the top patches
-on mywork reapplied on top of the modified commit you created in TMP. You can
+When you're done, you'll be left with mywork checked out, with the top
+patches on mywork reapplied on top of your modified commit. You can
then clean up with
-------------------------------------------------
-$ git branch -d TMP
$ git tag -d bad
-------------------------------------------------
"modified" existing commits; instead, you have replaced the old commits with
new commits having new object names.
+[[reordering-patch-series]]
Reordering or selecting from a patch series
-------------------------------------------
Then modify, reorder, or eliminate patches as preferred before applying
them again with gitlink:git-am[1].
+[[patch-series-tools]]
Other tools
-----------
purpose of maintaining a patch series. These are outside of the scope of
this manual.
+[[problems-with-rewriting-history]]
Problems with rewriting history
-------------------------------
For true distributed development that supports proper merging,
published branches should never be rewritten.
+[[advanced-branch-management]]
Advanced branch management
==========================
+[[fetching-individual-branches]]
Fetching individual branches
----------------------------
will create a new branch named "example-master" and store in it the
branch named "master" from the repository at the given URL. If you
already have a branch named example-master, it will attempt to
-"fast-forward" to the commit given by example.com's master branch. So
-next we explain what a fast-forward is:
+<<fast-forwards,fast-forward>> to the commit given by example.com's
+master branch. In more detail:
-[[fast-forwards]]
-Understanding git history: fast-forwards
-----------------------------------------
+[[fetch-fast-forwards]]
+git fetch and fast-forwards
+---------------------------
In the previous example, when updating an existing branch, "git
fetch" checks to make sure that the most recent commit on the remote
branch is a descendant of the most recent commit on your copy of the
branch before updating your copy of the branch to point at the new
-commit. Git calls this process a "fast forward".
+commit. Git calls this process a <<fast-forwards,fast forward>>.
A fast forward looks something like this:
unless you've already created a reference of your own pointing to
them.
+[[forcing-fetch]]
Forcing git fetch to do non-fast-forward updates
------------------------------------------------
$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
-------------------------------------------------
-Note the addition of the "+" sign. Be aware that commits that the
-old version of example/master pointed at may be lost, as we saw in
-the previous section.
+Note the addition of the "+" sign. Alternatively, you can use the "-f"
+flag to force updates of all the fetched branches, as in:
+-------------------------------------------------
+$ git fetch -f origin
+-------------------------------------------------
+
+Be aware that commits that the old version of example/master pointed at
+may be lost, as we saw in the previous section.
+
+[[remote-branch-configuration]]
Configuring remote branches
---------------------------
then the following commands will all do the same thing:
-------------------------------------------------
-$ git fetch git://example.com/proj.git master:ref/remotes/example/master
-$ git fetch example master:ref/remotes/example/master
-$ git fetch example example/master
+$ git fetch git://example.com/proj.git master:refs/remotes/example/master
+$ git fetch example master:refs/remotes/example/master
$ git fetch example
-------------------------------------------------
Git internals
=============
-There are two object abstractions: the "object database", and the
-"current directory cache" aka "index".
+Git depends on two fundamental abstractions: the "object database", and
+the "current directory cache" aka "index".
+[[the-object-database]]
The Object Database
-------------------
to other objects (by referencing their SHA1 hash), and so you can
build up a hierarchy of objects.
-All objects have a statically determined "type" aka "tag", which is
+All objects have a statically determined "type" which is
determined at object creation time, and which identifies the format of
the object (i.e. how it is used, and how it can refer to other
objects). There are currently four different object types: "blob",
-"tree", "commit" and "tag".
+"tree", "commit", and "tag".
-A "blob" object cannot refer to any other object, and is, like the type
-implies, a pure storage object containing some user data. It is used to
-actually store the file data, i.e. a blob object is associated with some
-particular version of some file.
+A <<def_blob_object,"blob" object>> cannot refer to any other object,
+and is, as the name implies, a pure storage object containing some
+user data. It is used to actually store the file data, i.e. a blob
+object is associated with some particular version of some file.
-A "tree" object is an object that ties one or more "blob" objects into a
-directory structure. In addition, a tree object can refer to other tree
-objects, thus creating a directory hierarchy.
+A <<def_tree_object,"tree" object>> is an object that ties one or more
+"blob" objects into a directory structure. In addition, a tree object
+can refer to other tree objects, thus creating a directory hierarchy.
-A "commit" object ties such directory hierarchies together into
-a DAG of revisions - each "commit" is associated with exactly one tree
-(the directory hierarchy at the time of the commit). In addition, a
-"commit" refers to one or more "parent" commit objects that describe the
-history of how we arrived at that directory hierarchy.
+A <<def_commit_object,"commit" object>> ties such directory hierarchies
+together into a <<def_DAG,directed acyclic graph>> of revisions - each
+"commit" is associated with exactly one tree (the directory hierarchy at
+the time of the commit). In addition, a "commit" refers to one or more
+"parent" commit objects that describe the history of how we arrived at
+that directory hierarchy.
As a special case, a commit object with no parents is called the "root"
-object, and is the point of an initial project commit. Each project
+commit, and is the point of an initial project commit. Each project
must have at least one root, and while you can tie several different
root objects together into one project by creating a commit object which
has two or more separate roots as its ultimate parents, that's probably
just going to confuse people. So aim for the notion of "one root object
per project", even if git itself does not enforce that.
-A "tag" object symbolically identifies and can be used to sign other
-objects. It contains the identifier and type of another object, a
-symbolic name (of course!) and, optionally, a signature.
+A <<def_tag_object,"tag" object>> symbolically identifies and can be
+used to sign other objects. It contains the identifier and type of
+another object, a symbolic name (of course!) and, optionally, a
+signature.
Regardless of object type, all objects share the following
characteristics: they are all deflated with zlib, and have a header
The object types in some more detail:
+[[blob-object]]
Blob Object
-----------
A blob is typically created when gitlink:git-update-index[1]
is run, and its data can be accessed by gitlink:git-cat-file[1].
+[[tree-object]]
Tree Object
-----------
its data can be accessed by gitlink:git-ls-tree[1].
Two trees can be compared with gitlink:git-diff-tree[1].
+[[commit-object]]
Commit Object
-------------
The parents do not have to actually have any relationship with the
result, for example.
-Note on commits: unlike real SCM's, commits do not contain
+Note on commits: unlike some SCM's, commits do not contain
rename information or file mode change information. All of that is
implicit in the trees involved (the result tree, and the result trees
of the parents), and describing that makes no sense in this idiotic
A commit is created with gitlink:git-commit-tree[1] and
its data can be accessed by gitlink:git-cat-file[1].
+[[trust]]
Trust
-----
To assist in this, git also provides the tag object...
+[[tag-object]]
Tag Object
----------
gitlink:git-verify-tag[1].
+[[the-index]]
The "index" aka "Current Directory Cache"
-----------------------------------------
The index is a simple binary file, which contains an efficient
-representation of a virtual directory content at some random time. It
+representation of the contents of a virtual directory. It
does so by a simple array that associates a set of names, dates,
permissions and content (aka "blob") objects together. The cache is
always kept ordered by name, and names are unique (with a few very
+[[the-workflow]]
The Workflow
------------
from the database or from the working directory. Thus there are four
main combinations:
+[[working-directory-to-index]]
working directory -> index
~~~~~~~~~~~~~~~~~~~~~~~~~~
it will only update the fields that are used to quickly test whether
an object still matches its old backing store object.
+[[index-to-object-database]]
index -> object database
~~~~~~~~~~~~~~~~~~~~~~~~
use that tree to re-generate the index at any time by going in the
other direction:
+[[object-database-to-index]]
object database -> index
~~~~~~~~~~~~~~~~~~~~~~~~
earlier. However, that is only your 'index' file: your working
directory contents have not been modified.
+[[index-to-working-directory]]
index -> working directory
~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally, there are a few odds and ends which are not purely moving
from one representation to the other:
+[[tying-it-all-together]]
Tying it all together
~~~~~~~~~~~~~~~~~~~~~
------------
+[[examining-the-data]]
Examining the data
------------------
to see what the top commit was.
+[[merging-multiple-trees]]
Merging multiple trees
----------------------
object.
Once you know the three trees you are going to merge (the one "original"
-tree, aka the common case, and the two "result" trees, aka the branches
+tree, aka the common tree, and the two "result" trees, aka the branches
you want to merge), you do a "merge" read into the index. This will
complain if it has to throw away your old index contents, so you should
make sure that you've committed those - in fact you would normally
`git-write-tree`.
+[[merging-multiple-trees-2]]
Merging multiple trees, continued
---------------------------------
above example shows is that file `hello.c` was changed from
`$orig` to `HEAD` and `$orig` to `$target` in a different way.
You could resolve this by running your favorite 3-way merge
-program, e.g. `diff3` or `merge`, on the blob objects from
-these three stages yourself, like this:
+program, e.g. `diff3`, `merge`, or git's own merge-file, on
+the blob objects from these three stages yourself, like this:
------------------------------------------------
$ git-cat-file blob 263414f... >hello.c~1
$ git-cat-file blob 06fa6a2... >hello.c~2
$ git-cat-file blob cc44c73... >hello.c~3
-$ merge hello.c~2 hello.c~1 hello.c~3
+$ git merge-file hello.c~2 hello.c~1 hello.c~3
------------------------------------------------
This would leave the merge result in `hello.c~2` file, along
and that is what higher level `git merge -s resolve` is implemented with.
+[[pack-files]]
How git stores objects efficiently: pack files
----------------------------------------------
The most common cause of dangling objects is that you've rebased a
branch, or you have pulled from somebody else who rebased a branch--see
<<cleaning-up-history>>. In that case, the old head of the original
-branch still exists, as does obviously everything it pointed to. The
-branch pointer itself just doesn't, since you replaced it with another
-one.
+branch still exists, as does everything it pointed to. The branch
+pointer itself just doesn't, since you replaced it with another one.
-There are also other situations too that cause dangling objects. For
+There are also other situations that cause dangling objects. For
example, a "dangling blob" may arise because you did a "git add" of a
file, but then, before you actually committed it and made it part of the
bigger picture, you changed something else in that file and committed
that you really didn't want to - you can look at what dangling objects
you have, and decide to reset your head to some old dangling state).
-For commits, the most useful thing to do with dangling objects tends to
-be to do a simple
+For commits, you can just use:
------------------------------------------------
$ gitk <dangling-commit-sha-goes-here> --not --all
------------------------------------------------
-For blobs and trees, you can't do the same, but you can examine them.
-You can just do
+This asks for all the history reachable from the given commit but not
+from any branch, tag, or other reference. If you decide it's something
+you want, you can always create a new reference to it, e.g.,
+
+------------------------------------------------
+$ git branch recovered-branch <dangling-commit-sha-goes-here>
+------------------------------------------------
+
+For blobs and trees, you can't do the same, but you can still examine
+them. You can just do
------------------------------------------------
$ git show <dangling-blob/tree-sha-goes-here>
contrast, running "git prune" while somebody is actively changing the
repository is a *BAD* idea).
+[[birdview-on-the-source-code]]
+A birds-eye view of Git's source code
+-------------------------------------
+
+It is not always easy for new developers to find their way through Git's
+source code. This section gives you a little guidance to show where to
+start.
+
+A good place to start is with the contents of the initial commit, with:
+
+----------------------------------------------------
+$ git checkout e83c5163
+----------------------------------------------------
+
+The initial revision lays the foundation for almost everything git has
+today, but is small enough to read in one sitting.
+
+Note that terminology has changed since that revision. For example, the
+README in that revision uses the word "changeset" to describe what we
+now call a <<def_commit_object,commit>>.
+
+Also, we do not call it "cache" any more, but "index", however, the
+file is still called `cache.h`. Remark: Not much reason to change it now,
+especially since there is no good single name for it anyway, because it is
+basically _the_ header file which is included by _all_ of Git's C sources.
+
+If you grasp the ideas in that initial commit, you should check out a
+more recent version and skim `cache.h`, `object.h` and `commit.h`.
+
+In the early days, Git (in the tradition of UNIX) was a bunch of programs
+which were extremely simple, and which you used in scripts, piping the
+output of one into another. This turned out to be good for initial
+development, since it was easier to test new things. However, recently
+many of these parts have become builtins, and some of the core has been
+"libified", i.e. put into libgit.a for performance, portability reasons,
+and to avoid code duplication.
+
+By now, you know what the index is (and find the corresponding data
+structures in `cache.h`), and that there are just a couple of object types
+(blobs, trees, commits and tags) which inherit their common structure from
+`struct object`, which is their first member (and thus, you can cast e.g.
+`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e.
+get at the object name and flags).
+
+Now is a good point to take a break to let this information sink in.
+
+Next step: get familiar with the object naming. Read <<naming-commits>>.
+There are quite a few ways to name an object (and not only revisions!).
+All of these are handled in `sha1_name.c`. Just have a quick look at
+the function `get_sha1()`. A lot of the special handling is done by
+functions like `get_sha1_basic()` or the likes.
+
+This is just to get you into the groove for the most libified part of Git:
+the revision walker.
+
+Basically, the initial version of `git log` was a shell script:
+
+----------------------------------------------------------------
+$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
+ LESS=-S ${PAGER:-less}
+----------------------------------------------------------------
+
+What does this mean?
+
+`git-rev-list` is the original version of the revision walker, which
+_always_ printed a list of revisions to stdout. It is still functional,
+and needs to, since most new Git programs start out as scripts using
+`git-rev-list`.
+
+`git-rev-parse` is not as important any more; it was only used to filter out
+options that were relevant for the different plumbing commands that were
+called by the script.
+
+Most of what `git-rev-list` did is contained in `revision.c` and
+`revision.h`. It wraps the options in a struct named `rev_info`, which
+controls how and what revisions are walked, and more.
+
+The original job of `git-rev-parse` is now taken by the function
+`setup_revisions()`, which parses the revisions and the common command line
+options for the revision walker. This information is stored in the struct
+`rev_info` for later consumption. You can do your own command line option
+parsing after calling `setup_revisions()`. After that, you have to call
+`prepare_revision_walk()` for initialization, and then you can get the
+commits one by one with the function `get_revision()`.
+
+If you are interested in more details of the revision walking process,
+just have a look at the first implementation of `cmd_log()`; call
+`git-show v1.3.0~155^2~4` and scroll down to that function (note that you
+no longer need to call `setup_pager()` directly).
+
+Nowadays, `git log` is a builtin, which means that it is _contained_ in the
+command `git`. The source side of a builtin is
+
+- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`,
+ and declared in `builtin.h`,
+
+- an entry in the `commands[]` array in `git.c`, and
+
+- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
+
+Sometimes, more than one builtin is contained in one source file. For
+example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`,
+since they share quite a bit of code. In that case, the commands which are
+_not_ named like the `.c` file in which they live have to be listed in
+`BUILT_INS` in the `Makefile`.
+
+`git log` looks more complicated in C than it does in the original script,
+but that allows for a much greater flexibility and performance.
+
+Here again it is a good point to take a pause.
+
+Lesson three is: study the code. Really, it is the best way to learn about
+the organization of Git (after you know the basic concepts).
+
+So, think about something which you are interested in, say, "how can I
+access a blob just knowing the object name of it?". The first step is to
+find a Git command with which you can do it. In this example, it is either
+`git show` or `git cat-file`.
+
+For the sake of clarity, let's stay with `git cat-file`, because it
+
+- is plumbing, and
+
+- was around even in the initial commit (it literally went only through
+ some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c`
+ when made a builtin, and then saw less than 10 versions).
+
+So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what
+it does.
+
+------------------------------------------------------------------
+ git_config(git_default_config);
+ if (argc != 3)
+ usage("git-cat-file [-t|-s|-e|-p|<type>] <sha1>");
+ if (get_sha1(argv[2], sha1))
+ die("Not a valid object name %s", argv[2]);
+------------------------------------------------------------------
+
+Let's skip over the obvious details; the only really interesting part
+here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
+object name, and if it refers to an object which is present in the current
+repository, it writes the resulting SHA-1 into the variable `sha1`.
+
+Two things are interesting here:
+
+- `get_sha1()` returns 0 on _success_. This might surprise some new
+ Git hackers, but there is a long tradition in UNIX to return different
+ negative numbers in case of different errors -- and 0 on success.
+
+- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
+ char \*`, but is actually expected to be a pointer to `unsigned
+ char[20]`. This variable will contain the 160-bit SHA-1 of the given
+ commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it
+ is the binary representation, as opposed to the ASCII representation in
+ hex characters, which is passed as `char *`.
+
+You will see both of these things throughout the code.
+
+Now, for the meat:
+
+-----------------------------------------------------------------------------
+ case 0:
+ buf = read_object_with_reference(sha1, argv[1], &size, NULL);
+-----------------------------------------------------------------------------
+
+This is how you read a blob (actually, not only a blob, but any type of
+object). To know how the function `read_object_with_reference()` actually
+works, find the source code for it (something like `git grep
+read_object_with | grep ":[a-z]"` in the git repository), and read
+the source.
+
+To find out how the result can be used, just read on in `cmd_cat_file()`:
+
+-----------------------------------
+ write_or_die(1, buf, size);
+-----------------------------------
+
+Sometimes, you do not know where to look for a feature. In many such cases,
+it helps to search through the output of `git log`, and then `git show` the
+corresponding commit.
+
+Example: If you know that there was some test case for `git bundle`, but
+do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
+does not illustrate the point!):
+
+------------------------
+$ git log --no-merges t/
+------------------------
+
+In the pager (`less`), just search for "bundle", go a few lines back,
+and see that it is in commit 18449ab0... Now just copy this object name,
+and paste it into the command line
+
+-------------------
+$ git show 18449ab0
+-------------------
+
+Voila.
+
+Another example: Find out what to do in order to make some script a
+builtin:
+
+-------------------------------------------------
+$ git log --no-merges --diff-filter=A builtin-*.c
+-------------------------------------------------
+
+You see, Git is actually the best tool to find out about the source of Git
+itself!
+
+[[glossary]]
include::glossary.txt[]
-Notes and todo list for this manual
-===================================
+[[git-quick-start]]
+Appendix A: Git Quick Start
+===========================
+
+This is a quick summary of the major commands; the following chapters
+will explain how these work in more detail.
+
+[[quick-creating-a-new-repository]]
+Creating a new repository
+-------------------------
+
+From a tarball:
+
+-----------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init
+Initialized empty Git repository in .git/
+$ git add .
+$ git commit
+-----------------------------------------------
+
+From a remote repository:
+
+-----------------------------------------------
+$ git clone git://example.com/pub/project.git
+$ cd project
+-----------------------------------------------
+
+[[managing-branches]]
+Managing branches
+-----------------
+
+-----------------------------------------------
+$ git branch # list all local branches in this repo
+$ git checkout test # switch working directory to branch "test"
+$ git branch new # create branch "new" starting at current HEAD
+$ git branch -d new # delete branch "new"
+-----------------------------------------------
+
+Instead of basing new branch on current HEAD (the default), use:
+
+-----------------------------------------------
+$ git branch new test # branch named "test"
+$ git branch new v2.6.15 # tag named v2.6.15
+$ git branch new HEAD^ # commit before the most recent
+$ git branch new HEAD^^ # commit before that
+$ git branch new test~10 # ten commits before tip of branch "test"
+-----------------------------------------------
+
+Create and switch to a new branch at the same time:
+
+-----------------------------------------------
+$ git checkout -b new v2.6.15
+-----------------------------------------------
+
+Update and examine branches from the repository you cloned from:
+
+-----------------------------------------------
+$ git fetch # update
+$ git branch -r # list
+ origin/master
+ origin/next
+ ...
+$ git checkout -b masterwork origin/master
+-----------------------------------------------
+
+Fetch a branch from a different repository, and give it a new
+name in your repository:
+
+-----------------------------------------------
+$ git fetch git://example.com/project.git theirbranch:mybranch
+$ git fetch git://example.com/project.git v2.6.15:mybranch
+-----------------------------------------------
+
+Keep a list of repositories you work with regularly:
+
+-----------------------------------------------
+$ git remote add example git://example.com/project.git
+$ git remote # list remote repositories
+example
+origin
+$ git remote show example # get details
+* remote example
+ URL: git://example.com/project.git
+ Tracked remote branches
+ master next ...
+$ git fetch example # update branches from example
+$ git branch -r # list all remote branches
+-----------------------------------------------
+
+
+[[exploring-history]]
+Exploring history
+-----------------
+
+-----------------------------------------------
+$ gitk # visualize and browse history
+$ git log # list all commits
+$ git log src/ # ...modifying src/
+$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
+$ git log master..test # ...in branch test, not in branch master
+$ git log test..master # ...in branch master, but not in test
+$ git log test...master # ...in one branch, not in both
+$ git log -S'foo()' # ...where difference contain "foo()"
+$ git log --since="2 weeks ago"
+$ git log -p # show patches as well
+$ git show # most recent commit
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
+$ git diff v2.6.15..HEAD # diff with current head
+$ git grep "foo()" # search working directory for "foo()"
+$ git grep v2.6.15 "foo()" # search old tree for "foo()"
+$ git show v2.6.15:a.txt # look at old version of a.txt
+-----------------------------------------------
+
+Search for regressions:
+
+-----------------------------------------------
+$ git bisect start
+$ git bisect bad # current version is bad
+$ git bisect good v2.6.13-rc2 # last known good revision
+Bisecting: 675 revisions left to test after this
+ # test here, then:
+$ git bisect good # if this revision is good, or
+$ git bisect bad # if this revision is bad.
+ # repeat until done.
+-----------------------------------------------
+
+[[making-changes]]
+Making changes
+--------------
+
+Make sure git knows who to blame:
+
+------------------------------------------------
+$ cat >>~/.gitconfig <<\EOF
+[user]
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
+EOF
+------------------------------------------------
+
+Select file contents to include in the next commit, then make the
+commit:
+
+-----------------------------------------------
+$ git add a.txt # updated file
+$ git add b.txt # new file
+$ git rm c.txt # old file
+$ git commit
+-----------------------------------------------
+
+Or, prepare and create the commit in one step:
+
+-----------------------------------------------
+$ git commit d.txt # use latest content only of d.txt
+$ git commit -a # use latest content of all tracked files
+-----------------------------------------------
+
+[[merging]]
+Merging
+-------
+
+-----------------------------------------------
+$ git merge test # merge branch "test" into the current branch
+$ git pull git://example.com/project.git master
+ # fetch and merge in remote branch
+$ git pull . test # equivalent to git merge test
+-----------------------------------------------
+
+[[sharing-your-changes]]
+Sharing your changes
+--------------------
+
+Importing or exporting patches:
+
+-----------------------------------------------
+$ git format-patch origin..HEAD # format a patch for each commit
+ # in HEAD but not in origin
+$ git am mbox # import patches from the mailbox "mbox"
+-----------------------------------------------
+
+Fetch a branch in a different git repository, then merge into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch
+-----------------------------------------------
+
+Store the fetched branch into a local branch before merging into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch:mybranch
+-----------------------------------------------
+
+After creating commits on a local branch, update the remote
+branch with your commits:
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git mybranch:theirbranch
+-----------------------------------------------
+
+When remote and local branch are both named "test":
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git test
+-----------------------------------------------
+
+Shortcut version for a frequently used remote repository:
+
+-----------------------------------------------
+$ git remote add example ssh://example.com/project.git
+$ git push example test
+-----------------------------------------------
+
+[[repository-maintenance]]
+Repository maintenance
+----------------------
+
+Check for corruption:
+
+-----------------------------------------------
+$ git fsck
+-----------------------------------------------
+
+Recompress, remove unused cruft:
+
+-----------------------------------------------
+$ git gc
+-----------------------------------------------
+
+
+[[todo]]
+Appendix B: Notes and todo list for this manual
+===============================================
This is a work in progress.
allow people to get to important topics without necessarily reading
everything in between.
-Say something about .gitignore.
-
Scan Documentation/ for other stuff left out; in particular:
howto's
some of technical/?