-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
See also <<git-quick-start>> for a brief overview of git commands,
without any explanation.
-Also, see <<todo>> for ways that you can help make this manual more
+Finally, see <<todo>> for ways that you can help make this manual more
complete.
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
-------------------------------------------------
will use HEAD to produce a tar archive in which each filename is
-preceded by "prefix/".
+preceded by "project/".
If you're releasing a new version of a software project, you may want
to simultaneously make a changelog to include in the release
and then he just cut-and-pastes the output commands after verifying that
they look OK.
+[[Finding-comments-with-given-content]]
Finding commits referencing a file with given content
-----------------------------------------------------
-------------------------------------------------
$ 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
-------------------------
-------------------------------------------------
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
+extra disk space. They can sometimes provide a last-resort method for
+recovering lost work--see <<dangling-objects>> for details. However, if
+you wish, you can remove them with gitlink:git-prune[1] or the --prune
option to gitlink:git-gc[1]:
-------------------------------------------------
$ 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 origin/maint 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
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
+commands that accept repository URLs as arguments will also accept a
local directory name:
-------------------------------------------------
$ git pull /path/to/other/repository
-------------------------------------------------
+or an ssh url:
+
+-------------------------------------------------
+$ git clone ssh://yourhost/~you/repository
+-------------------------------------------------
+
+For projects with few developers, or for synchronizing a few private
+repositories, this may be all you need.
+
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
| they push V
their public repo <------------------- their repo
+We explain how to do this in the following sections.
+
[[setting-up-a-public-repository]]
Setting up a public repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
$ git push ssh://yourserver.com/~you/proj.git +master
-------------------------------------------------
+Note that the target of a "push" is normally a
+<<def_bare_repository,bare>> repository. You can also push to a
+repository that has a checked-out working tree, but the working tree
+will not be updated by the push. This may lead to unexpected results if
+the branch you push to is the currently checked-out branch!
+
As with git-fetch, you may also set up configuration options to
save typing; so, for example, after
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 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.
independently of the contents or the type of the object: all objects can
be validated by verifying that (a) their hashes match the content of the
file and (b) the object successfully inflates to a stream of bytes that
-forms a sequence of <ascii type without space>
+ <space> + <ascii decimal
-size> + <byte\0> + <binary object data>.
+forms a sequence of <ascii type without space>
{plus} <space> {plus} <ascii decimal
+size> {plus} <byte\0> {plus} <binary object data>.
The structured objects can further have their structure and
connectivity to other objects verified. This is generally done with
haven't lost any information as long as you have the name of the tree
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.
include::glossary.txt[]
[[git-quick-start]]
-Appendix A: Git Quick Start
-===========================
+Appendix A: Git Quick Reference
+===============================
-This is a quick summary of the major commands; the following chapters
-will explain how these work in more detail.
+This is a quick summary of the major commands; the previous chapters
+explain how these work in more detail.
[[quick-creating-a-new-repository]]
Creating a new repository
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
More details on gitweb?
Write a chapter on using plumbing and writing scripts.
+
+Alternates, clone -reference, etc.
+
+git unpack-objects -r for recovery
projects / thirdparty / git.git / blobdiff