-Git User's Manual (for version 1.5.1 or newer)
+Git User's Manual (for version 1.5.3 or newer)
______________________________________________
Git is a fast distributed revision control system.
-This manual is designed to be readable by someone with basic unix
+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
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 gitlink:git-clone[1] command
-to download a copy of an existing repository for a project that you
-are interested in. If you don't already have a project in mind, here
-are some interesting examples:
+The best way to get one is by using the gitlink: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. 10MB download):
together with a special top-level directory named ".git", which
contains all the information about the history of the project.
-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
-------------------------------------------------
-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 (versions) of the project's
-contents.
+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>>.
A single git repository may contain multiple branches. It keeps track
of them by keeping a list of <<def_head,heads>> which reference the
-latest version on each branch; the gitlink:git-branch[1] command shows
+latest commit on each branch; the gitlink:git-branch[1] command shows
you the list of branch heads:
------------------------------------------------
------------------------------------------------
$ git show
-commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
-Author: Jamal Hadi Salim <hadi@cyberus.ca>
-Date: Sat Dec 2 22:22:25 2006 -0800
-
- [XFRM]: Fix aevent structuring to be more complete.
-
- aevents can not uniquely identify an SA. We break the ABI with this
- patch, but consensus is that since it is not yet utilized by any
- (known) application then it is fine (better do it now than later).
-
- Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
- Signed-off-by: David S. Miller <davem@davemloft.net>
-
-diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
-index 8be626f..d7aac9d 100644
---- a/Documentation/networking/xfrm_sync.txt
-+++ b/Documentation/networking/xfrm_sync.txt
-@@ -47,10 +47,13 @@ aevent_id structure looks like:
+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 @@
- struct xfrm_aevent_id {
- struct xfrm_usersa_id sa_id;
-+ xfrm_address_t saddr;
- __u32 flags;
-+ __u32 reqid;
- };
-...
+ 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
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 descendent of X, or that there is a chain of parents
+that Y is a descendant of X, or that there is a chain of parents
leading from commit Y to commit X.
[[history-diagrams]]
Git is best thought of as a tool for storing the history of a
collection of files. It does this by storing compressed snapshots of
-the contents of a file heirarchy, together with "commits" which show
+the contents of a file hierarchy, together with "commits" which show
the relationships between these snapshots.
Git provides extremely flexible and fast tools for exploring the
[[Finding-comments-with-given-content]]
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 |
+$ git log --raw --abbrev=40 --pretty=oneline -- filename |
grep -B 1 `git hash-object filename`
-------------------------------------------------
-------------------------------------------------
As a special shortcut,
-
+
-------------------------------------------------
$ git commit -a
-------------------------------------------------
-------------------------------------------------
$ git diff --cached # difference between HEAD and the index; what
- # would be commited if you ran "commit" now.
+ # would be committed if you ran "commit" now.
$ git diff # difference between the index file and your
# working directory; changes that would not
# be included if you ran "commit" now.
$ git status # a brief per-file summary of the above.
-------------------------------------------------
+You can also use gitlink:git-gui[1] to create commits, view changes in
+the index and the working tree files, and individually select diff hunks
+for inclusion in the index (by right-clicking on the diff hunk and
+choosing "Stage Hunk For Commit").
+
[[creating-good-commit-messages]]
Creating good commit messages
-----------------------------
++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
-------------------------------------------------
-Recall that the commit which will be commited after we resolve this
+Recall that the commit which will be committed after we resolve this
conflict will have two parents instead of the usual one: one parent
will be HEAD, the tip of the current branch; the other will be the
tip of the other branch, which is stored temporarily in MERGE_HEAD.
$ git reset --hard HEAD
-------------------------------------------------
-Or, if you've already commited the merge that you want to throw away,
+Or, if you've already committed the merge that you want to throw away,
-------------------------------------------------
$ git reset --hard ORIG_HEAD
which will display the given version of the file.
+[[interrupted-work]]
+Temporarily setting aside work in progress
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While you are in the middle of working on something complicated, you
+find an unrelated but obvious and trivial bug. You would like to fix it
+before continuing. You can use gitlink:git-stash[1] to save the current
+state of your work, and after fixing the bug (or, optionally after doing
+so on a different branch and then coming back), unstash the
+work-in-progress changes.
+
+------------------------------------------------
+$ git stash "work in progress for foo feature"
+------------------------------------------------
+
+This command will save your changes away to the `stash`, and
+reset your working tree and the index to match the tip of your
+current branch. Then you can make your fix as usual.
+
+------------------------------------------------
+... edit and test ...
+$ git commit -a -m "blorpl: typofix"
+------------------------------------------------
+
+After that, you can go back to what you were working on with
+`git stash apply`:
+
+------------------------------------------------
+$ git stash apply
+------------------------------------------------
+
+
[[ensuring-good-performance]]
Ensuring good performance
-------------------------
Fortunately, git also keeps a log, called a "reflog", of all the
previous values of each branch. So in this case you can still find the
-old history using, for example,
+old history using, for example,
-------------------------------------------------
$ git log master@{1}
reference pointing to it, for example, a new branch:
------------------------------------------------
-$ git branch recovered-branch 7281251ddd
+$ git branch recovered-branch 7281251ddd
------------------------------------------------
Other types of dangling objects (blobs and trees) are also possible, and
$ git pull origin master
-------------------------------------------------
-In fact, "origin" is normally the default repository to pull from,
-and the default branch is normally the HEAD of the remote repository,
-so often you can accomplish the above with just
+In fact, if you have "master" checked out, then by default "git pull"
+merges from the HEAD branch of the origin repository. So often you can
+accomplish the above with just a simple
-------------------------------------------------
$ 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. 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 maint origin/maint
--------------------------------------------------
+More generally, a branch that is created from a remote branch will pull
+by default from that branch. See the descriptions of the
+branch.<name>.remote and branch.<name>.merge options in
+gitlink:git-config[1], and the discussion of the --track option in
+gitlink:git-checkout[1], to learn how to control these defaults.
In addition to saving you keystrokes, "git pull" also helps you by
producing a default commit message documenting the branch and
Public git repositories
-----------------------
-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.
+Another way to submit changes to a project is to tell the maintainer
+of that project to pull the changes from your repository using
+gitlink: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 the maintainer both have accounts on the same machine, then
you can just pull changes from each other's repositories directly;
you push
your personal repo ------------------> your public repo
- ^ |
+ ^ |
| |
| you pull | they pull
| |
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:
+clone or pull from that url, for example with a command line like:
-------------------------------------------------
$ git clone http://yourserver.com/~you/proj.git
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>>.
+gitlink: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
\ \
a--b--c--m <-- mywork
................................................
-
+
However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
gitlink:git-rebase[1]:
And browse through the list of patches in the mywork branch using gitk,
applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using commit
---amend.
+cherry-pick, and possibly modifying them as you go using commit --amend.
+The gitlink:git-gui[1] command may also help as it allows you to
+individually select diff hunks for inclusion in the index (by
+right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
Another technique is to use git-format-patch to create a series of
patches, then reset the state to before the patches:
Other tools
-----------
-There are numerous other tools, such as stgit, which exist for the
+There are numerous other tools, such as StGIT, which exist for the
purpose of maintaining a patch series. These are outside of the scope of
this manual.
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.
+per project", even if git itself does not enforce that.
A <<def_tag_object,"tag" object>> symbolically identifies and can be
used to sign other objects. It contains the identifier and type of
known tree object, or update/compare it with a live tree that is being
developed. If you blow the directory cache away entirely, you generally
haven't lost any information as long as you have the name of the tree
-that it described.
+that it described.
-At the same time, the index is at the same time also the
-staging area for creating new trees, and creating a new tree always
-involves a controlled modification of the index file. In particular,
-the index file can have the representation of an intermediate tree that
-has not yet been instantiated. So the index can be thought of as a
-write-back cache, which can contain dirty information that has not yet
-been written back to the backing store.
+At the same time, the index is also the staging area for creating
+new trees, and creating a new tree always involves a controlled
+modification of the index file. In particular, the index file can
+have the representation of an intermediate tree that has not yet been
+instantiated. So the index can be thought of as a write-back cache,
+which can contain dirty information that has not yet been written back
+to the backing store.
work *purely* on the index file (showing the current state of the
index), but most operations move data to and from the index file. Either
from the database or from the working directory. Thus there are four
-main combinations:
+main combinations:
[[working-directory-to-index]]
working directory -> index
leaving _some_ of the new objects in the object database, but just
dangling and useless.
-Anyway, once you are sure that you're not interested in any dangling
+Anyway, once you are sure that you're not interested in any dangling
state, you can just prune all unreachable objects:
------------------------------------------------
repository - it's kind of like doing a filesystem fsck recovery: you
don't want to do that while the filesystem is mounted.
-(The same is true of "git-fsck" itself, btw - but since
-git-fsck never actually *changes* the repository, it just reports
-on what it found, git-fsck itself is never "dangerous" to run.
-Running it while somebody is actually changing the repository can cause
-confusing and scary messages, but it won't actually do anything bad. In
-contrast, running "git prune" while somebody is actively changing the
+(The same is true of "git-fsck" itself, btw - but since
+git-fsck never actually *changes* the repository, it just reports
+on what it found, git-fsck itself is never "dangerous" to run.
+Running it while somebody is actually changing the repository can cause
+confusing and scary messages, but it won't actually do anything bad. In
+contrast, running "git prune" while somebody is actively changing the
repository is a *BAD* idea).
[[birdview-on-the-source-code]]
The basic requirements:
- It must be readable in order, from beginning to end, by
- someone intelligent with a basic grasp of the unix
- commandline, but without any special knowledge of git. If
+ someone intelligent with a basic grasp of the UNIX
+ command line, but without any special knowledge of git. If
necessary, any other prerequisites should be specifically
mentioned as they arise.
- Whenever possible, section headings should clearly describe