regressions, and so on.
People needing to do actual development will also want to read
-<<Developing-with-git>> and <<sharing-development>>.
+<<Developing-With-git>> and <<sharing-development>>.
Further chapters cover more specialized topics.
Comprehensive reference documentation is available through the man
-pages. For a command such as "git clone", just use
+pages, or linkgit:git-help[1] command. For example, for the command
+"git clone <repo>", you can either use:
------------------------------------------------
$ man git-clone
------------------------------------------------
+or:
+
+------------------------------------------------
+$ git help clone
+------------------------------------------------
+
+With the latter, you can use the manual viewer of your choice; see
+linkgit:git-help[1] for more information.
+
See also <<git-quick-start>> for a brief overview of git commands,
without any explanation.
------------------------------------------------
# git itself (approx. 10MB download):
$ git clone git://git.kernel.org/pub/scm/git/git.git
- # the linux kernel (approx. 150MB download):
+ # the Linux kernel (approx. 150MB download):
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
------------------------------------------------
did, and why.
Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-"SHA1 id", shown on the first line of the "git show" output. You can usually
+"SHA1 id", shown on the first line of the "git-show" output. You can usually
refer to a commit by a shorter name, such as a tag or a branch name, but this
longer name can also be useful. Most importantly, it is a globally unique
name for this commit: so if you tell somebody else the object name (for
references with the same shorthand name, see the "SPECIFYING
REVISIONS" section of linkgit:git-rev-parse[1].
-[[Updating-a-repository-with-git-fetch]]
-Updating a repository with git fetch
+[[Updating-a-repository-With-git-fetch]]
+Updating a repository with git-fetch
------------------------------------
Eventually the developer cloned from will do additional work in her
-------------------------------------------------
New remote-tracking branches will be stored under the shorthand name
-that you gave "git remote add", in this case linux-nfs:
+that you gave "git-remote add", in this case linux-nfs:
-------------------------------------------------
$ git branch -r
-------------------------------------------------
If you run "git branch" at this point, you'll see that git has
-temporarily moved you to a new branch named "bisect". This branch
-points to a commit (with commit id 65934...) that is reachable from
-"master" but not from v2.6.18. Compile and test it, and see whether
-it crashes. Assume it does crash. Then:
+temporarily moved you in "(no branch)". HEAD is now detached from any
+branch and points directly to a commit (with commit id 65934...) that
+is reachable from "master" but not from v2.6.18. Compile and test it,
+and see whether it crashes. Assume it does crash. Then:
-------------------------------------------------
$ git bisect bad
$ git bisect reset
-------------------------------------------------
-to return you to the branch you were on before and delete the
-temporary "bisect" branch.
+to return you to the branch you were on before.
Note that the version which git-bisect checks out for you at each
point is just a suggestion, and you're free to try a different
-------------------------------------------------
which will run gitk and label the commit it chose with a marker that
-says "bisect". Chose a safe-looking commit nearby, note its commit
+says "bisect". Choose a safe-looking commit nearby, note its commit
id, and check it out with:
-------------------------------------------------
then test, run "bisect good" or "bisect bad" as appropriate, and
continue.
+Instead of "git bisect visualize" and then "git reset --hard
+fb47ddb2db...", you might just want to tell git that you want to skip
+the current commit:
+
+-------------------------------------------------
+$ git bisect skip
+-------------------------------------------------
+
+In this case, though, git may not eventually be able to tell the first
+bad one between some first skipped commits and a later bad commit.
+
+There are also ways to automate the bisecting process if you have a
+test script that can tell a good from a bad commit. See
+linkgit:git-bisect[1] for more information about this and other "git
+bisect" features.
+
[[naming-commits]]
Naming commits
--------------
and then he just cut-and-pastes the output commands after verifying that
they look OK.
-[[Finding-comments-with-given-content]]
+[[Finding-comments-With-given-Content]]
Finding commits referencing a file with given content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
linkgit:git-hash-object[1] man pages may prove helpful.
-[[Developing-with-git]]
+[[Developing-With-git]]
Developing with git
===================
If you have some initial content (say, a tarball):
-------------------------------------------------
-$ tar -xzvf project.tar.gz
+$ tar xzvf project.tar.gz
$ cd project
$ git init
$ git add . # include everything below ./ in the first commit:
shows the difference between the working tree and the index file.
-Note that "git add" always adds just the current contents of a file
+Note that "git-add" always adds just the current contents of a file
to the index; further changes to the same file will be ignored unless
you run git-add on the file again.
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
+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`".
+"`git add .`" practically useless, and they keep showing up in the output of
+"`git status`".
You can tell git to ignore certain files by creating a file called .gitignore
in the top level of your working directory, with contents such as:
-------------------------------------------------
$ git show :1:file.txt # the file in a common ancestor of both branches
-$ git show :2:file.txt # the version from HEAD, but including any
- # nonconflicting changes from MERGE_HEAD
-$ git show :3:file.txt # the version from MERGE_HEAD, but including any
- # nonconflicting changes from HEAD.
+$ git show :2:file.txt # the version from HEAD.
+$ git show :3:file.txt # the version from MERGE_HEAD.
-------------------------------------------------
-Since the stage 2 and stage 3 versions have already been updated with
-nonconflicting changes, the only remaining differences between them are
-the important ones; thus linkgit:git-diff[1] can use the information in
-the index to show only those conflicts.
+When you ask linkgit:git-diff[1] to show the conflicts, it runs a
+three-way diff between the conflicted merge results in the work tree with
+stages 2 and 3 to show only hunks whose contents come from both sides,
+mixed (in other words, when a hunk's merge results come only from stage 2,
+that part is not conflicting and is not shown. Same for stage 3).
The diff above shows the differences between the working-tree version of
file.txt and the stage 2 and stage 3 versions. So instead of preceding
$ git diff --theirs file.txt # same as the above.
-------------------------------------------------
-The linkgit:git-log[1] and gitk[1] commands also provide special help
+The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
for merges:
-------------------------------------------------
MERGE_HEAD, and which touch an unmerged file.
You may also use linkgit:git-mergetool[1], which lets you merge the
-unmerged files using external tools such as emacs or kdiff3.
+unmerged files using external tools such as Emacs or kdiff3.
Each time you resolve the conflicts in a file and update the index:
In the process of undoing a previous bad change, you may find it
useful to check out an older version of a particular file using
-linkgit:git-checkout[1]. We've used git checkout before to switch
+linkgit:git-checkout[1]. We've used git-checkout before to switch
branches, but it has quite different behavior if it is given a path
name: the command
work-in-progress changes.
------------------------------------------------
-$ git stash "work in progress for foo feature"
+$ git stash save "work in progress for foo feature"
------------------------------------------------
This command will save your changes away to the `stash`, and
Sharing development with others
===============================
-[[getting-updates-with-git-pull]]
-Getting updates with git pull
+[[getting-updates-With-git-pull]]
+Getting updates with git-pull
-----------------------------
After you clone a repository and make a few changes of your own, you
may wish to check the original repository for updates and merge them
into your own work.
-We have already seen <<Updating-a-repository-with-git-fetch,how to
+We have already seen <<Updating-a-repository-With-git-fetch,how to
keep remote tracking branches up to date>> with linkgit:git-fetch[1],
and how to merge two branches. So you can merge in changes from the
original repository's master branch with:
Another way to submit changes to a project is to tell the maintainer
of that project to pull the changes from your repository using
-linkgit:git-pull[1]. In the section "<<getting-updates-with-git-pull,
-Getting updates with git pull>>" we described this as a way to get
+linkgit: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.
$ mv proj.git /home/you/public_html/proj.git
$ cd proj.git
$ git --bare update-server-info
-$ chmod a+x hooks/post-update
+$ mv hooks/post-update.sample hooks/post-update
-------------------------------------------------
(For an explanation of the last two lines, see
-linkgit:git-update-server-info[1], and the documentation
-link:hooks.html[Hooks used by git].)
+linkgit:git-update-server-info[1] and linkgit:githooks[5].)
Advertise the URL of proj.git. Anybody else should then be able to
clone or pull from that URL, for example with a command line like:
This can happen, for example, if you:
- - use `git reset --hard` to remove already-published commits, or
- - use `git commit --amend` to replace already-published commits
+ - use `git-reset --hard` to remove already-published commits, or
+ - use `git-commit --amend` to replace already-published commits
(as in <<fixing-a-mistake-by-rewriting-history>>), or
- - use `git rebase` to rebase any already-published commits (as
+ - use `git-rebase` to rebase any already-published commits (as
in <<using-git-rebase>>).
You may force git-push to perform the update anyway by preceding the
Normally whenever a branch head in a public repository is modified, it
is modified to point to a descendant of the commit that it pointed to
before. By forcing a push in this situation, you break that convention.
-(See <<problems-with-rewriting-history>>.)
+(See <<problems-With-rewriting-history>>.)
Nevertheless, this is a common practice for people that need a simple
way to publish a work-in-progress patch series, and it is an acceptable
It's also possible for a push to fail in this way when other people have
the right to push to the same repository. In that case, the correct
-solution is to retry the push after first updating your work by either a
-pull or a fetch followed by a rebase; see the
+solution is to retry the push after first updating your work: either by a
+pull, or by a fetch followed by a rebase; see the
<<setting-up-a-shared-repository,next section>> and
-link:cvs-migration.html[git for CVS users] for more.
+linkgit:gitcvs-migration[7] for more.
[[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.html[git for CVS users] for instructions on how to
+linkgit:gitcvs-migration[7] for instructions on how to
set this up.
However, while there is nothing wrong with git's support for shared
changes are in a specific branch, use:
-------------------------------------------------
-$ git log linux..branchname | git-shortlog
+$ git log linux..branchname | git shortlog
-------------------------------------------------
To see whether it has already been merged into the test or release branches,
-------------------------------------------------
This will remove each of your commits from mywork, temporarily saving
-them as patches (in a directory named ".dotest"), update mywork to
+them as patches (in a directory named ".git/rebase-apply"), update mywork to
point at the latest version of origin, then apply each of the saved
patches to the new mywork. The result will look like:
................................................
In the process, it may discover conflicts. In that case it will stop
-and allow you to fix the conflicts; after fixing conflicts, use "git
-add" to update the index with those contents, and then, instead of
+and allow you to fix the conflicts; after fixing conflicts, use "git-add"
+to update the index with those contents, and then, instead of
running git-commit, just run
-------------------------------------------------
purpose of maintaining a patch series. These are outside of the scope of
this manual.
-[[problems-with-rewriting-history]]
+[[problems-With-rewriting-history]]
Problems with rewriting history
-------------------------------
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
+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-forwards,fast forward>>.
o--o--o <-- new head of the branch
................................................
-In this case, "git fetch" will fail, and print out a warning.
+In this case, "git-fetch" will fail, and print out a warning.
In that case, you can still force git to update to the new head, as
described in the following section. However, note that in the
them.
[[forcing-fetch]]
-Forcing git fetch to do non-fast-forward updates
+Forcing git-fetch to do non-fast-forward updates
------------------------------------------------
If git fetch fails because the new head of a branch is not a
-------------------------------------------------
Don't do this unless you're sure you won't mind "git fetch" possibly
-throwing away commits on mybranch.
+throwing away commits on 'example/master'.
Also note that all of the above configuration can be performed by
directly editing the file .git/config instead of using
"tag".
- A <<def_blob_object,"blob" object>> is used to store file data.
-- A <<def_tree_object,"tree" object>> is an object that ties one or more
+- A <<def_tree_object,"tree" object>> 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_commit_object,"commit" object>> ties such directory hierarchies
A tag object contains an object, object type, tag name, the name of the
person ("tagger") who created the tag, and a message, which may contain
-a signature, as can be seen using the linkgit:git-cat-file[1]:
+a signature, as can be seen using linkgit:git-cat-file[1]:
------------------------------------------------
$ git cat-file tag v1.5.0
to remove any of the "loose" objects that are now contained in the
pack. This will also remove any unreferenced objects (which may be
-created when, for example, you use "git reset" to remove a commit).
+created when, for example, you use "git-reset" to remove a commit).
You can verify that the loose objects are gone by looking at the
.git/objects directory or by running
pointer itself just doesn't, since you replaced it with another one.
There are also other situations that cause dangling objects. For
-example, a "dangling blob" may arise because you did a "git add" of a
+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 *updated* thing--the old state that you added originally ends up
almost always the result of either being a half-way mergebase (the blob
will often even have the conflict markers from a merge in it, if you
have had conflicting merges that you fixed up by hand), or simply
-because you interrupted a "git fetch" with ^C or something like that,
+because you interrupted a "git-fetch" with ^C or something like that,
leaving _some_ of the new objects in the object database, but just
dangling and useless.
Assume the output looks like this:
------------------------------------------------
-$ git-fsck --full
+$ git fsck --full
broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
to blob 4b9458b3786228369c63936db65827de3cc06200
missing blob 4b9458b3786228369c63936db65827de3cc06200
$ git init
$ for i in a b c d
do
- git submodule add ~/git/$i
+ git submodule add ~/git/$i $i
done
-------------------------------------------------
NOTE: Do not use local URLs here if you plan to publish your superproject!
-See what files `git submodule` created:
+See what files `git-submodule` created:
-------------------------------------------------
$ ls -a
. .. .git .gitmodules a b c d
-------------------------------------------------
-The `git submodule add` command does a couple of things:
+The `git-submodule add <repo> <path>` command does a couple of things:
-- It clones the submodule under the current directory and by default checks out
- the master branch.
+- It clones the submodule from <repo> to the given <path> under the
+ current directory and by default checks out the master branch.
- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
adds this file to the index, ready to be committed.
- It adds the submodule's current commit ID to the index, ready to be
$ git submodule init
-------------------------------------------------
-Now use `git submodule update` to clone the repositories and check out the
+Now use `git-submodule update` to clone the repositories and check out the
commits specified in the superproject:
-------------------------------------------------
. .. .git a.txt
-------------------------------------------------
-One major difference between `git submodule update` and `git submodule add` is
-that `git submodule update` checks out a specific commit, rather than the tip
+One major difference between `git-submodule update` and `git-submodule add` is
+that `git-submodule update` checks out a specific commit, rather than the tip
of a branch. It's like checking out a tag: the head is detached, so you're not
working on a branch.
considering a removed file to be a valid thing, and if the file really
does not exist any more, it will update the index accordingly.
-As a special case, you can also do `git-update-index --refresh`, which
+As a special case, you can also do `git update-index --refresh`, which
will refresh the "stat" information of each index to match the current
stat information. It will 'not' update the object status itself, and
it will only update the fields that are used to quickly test whether
index. Normal operation is just
-------------------------------------------------
-$ git-read-tree <sha1 of tree>
+$ git read-tree <sha1 of tree>
-------------------------------------------------
and your index file will now be equivalent to the tree that you saved
with
-------------------------------------------------
-$ git-checkout-index filename
+$ git checkout-index filename
-------------------------------------------------
or, if you want to check out all of the index, use `-a`.
Tying it all together
~~~~~~~~~~~~~~~~~~~~~
-To commit a tree you have instantiated with "git-write-tree", you'd
+To commit a tree you have instantiated with "git write-tree", you'd
create a "commit" object that refers to that tree and the history
behind it--most notably the "parent" commits that preceded it in
history.
state at the time of the commit, and a list of parents:
-------------------------------------------------
-$ git
-commit-tree <tree> -p <parent> [-p <parent2> ..]
+$ git
commit-tree <tree> -p <parent> [-p <parent2> ..]
-------------------------------------------------
and then giving the reason for the commit on stdin (either through
object:
-------------------------------------------------
-$ git-cat-file -t <objectname>
+$ git cat-file -t <objectname>
-------------------------------------------------
shows the type of the object, and once you have the type (which is
usually implicit in where you find the object), you can use
-------------------------------------------------
-$ git-cat-file blob|tree|commit|tag <objectname>
+$ git cat-file blob|tree|commit|tag <objectname>
-------------------------------------------------
to show its contents. NOTE! Trees have binary content, and as a result
you can do
-------------------------------------------------
-$ git-cat-file commit HEAD
+$ git cat-file commit HEAD
-------------------------------------------------
to see what the top commit was.
of two commits with
-------------------------------------------------
-$ git-merge-base <commit1> <commit2>
+$ git merge-base <commit1> <commit2>
-------------------------------------------------
which will return you the commit they are both based on. You should
do with (for example)
-------------------------------------------------
-$ git-cat-file commit <commitname> | head -1
+$ git cat-file commit <commitname> | head -1
-------------------------------------------------
since the tree object information is always the first line in a commit
To do the merge, do
-------------------------------------------------
-$ git-read-tree -m -u <origtree> <yourtree> <targettree>
+$ git read-tree -m -u <origtree> <yourtree> <targettree>
-------------------------------------------------
which will do all trivial merge operations for you directly in the
index file, and you can just write the result out with
-`git-write-tree`.
+`git write-tree`.
[[merging-multiple-trees-2]]
object, and you will have to resolve any such merge clashes using
other tools before you can write out the result.
-You can examine such index state with `git-ls-files --unmerged`
+You can examine such index state with `git ls-files --unmerged`
command. An example:
------------------------------------------------
-$ git-read-tree -m $orig HEAD $target
-$ git-ls-files --unmerged
+$ git read-tree -m $orig HEAD $target
+$ git ls-files --unmerged
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
------------------------------------------------
-Each line of the `git-ls-files --unmerged` output begins with
+Each line of the `git ls-files --unmerged` output begins with
the blob mode bits, blob SHA1, 'stage number', and the
filename. The 'stage number' is git's way to say which tree it
came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
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
+$ git cat-file blob 263414f... >hello.c~1
+$ git cat-file blob 06fa6a2... >hello.c~2
+$ git cat-file blob cc44c73... >hello.c~3
$ git merge-file hello.c~2 hello.c~1 hello.c~3
------------------------------------------------
-------------------------------------------------
$ mv -f hello.c~2 hello.c
-$ git-update-index hello.c
+$ git update-index hello.c
-------------------------------------------------
-When a path is in unmerged state, running `git-update-index` for
+When a path is in the "unmerged" state, running `git-update-index` for
that path tells git to mark the path resolved.
The above is the description of a git merge at the lowest level,
to help you understand what conceptually happens under the hood.
-In practice, nobody, not even git itself, uses three `git-cat-file`
-for this. There is `git-merge-index` program that extracts the
+In practice, nobody, not even git itself, runs `git-cat-file` three times
+for this. There is a `git-merge-index` program that extracts the
stages to temporary files and calls a "merge" script on it:
-------------------------------------------------
-$ git-merge-index git-merge-one-file hello.c
+$ git merge-index git-merge-one-file hello.c
-------------------------------------------------
-and that is what higher level `git merge -s resolve` is implemented with.
+and that is what higher level `git-merge -s resolve` is implemented with.
[[hacking-git]]
Hacking git
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
+Also, we do not call it "cache" any more, but rather "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.
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:
+Basically, the initial version of `git-log` was a shell script:
----------------------------------------------------------------
$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
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{tilde}155^2{tilde}4` and scroll down to that function (note that you
+`git show v1.3.0{tilde}155^2{tilde}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
+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`,
_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,
+`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.
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`.
+`git-show` or `git-cat-file`.
-For the sake of clarity, let's stay with `git cat-file`, because it
+For the sake of clarity, let's stay with `git-cat-file`, because it
- is plumbing, and
-----------------------------------
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
+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
+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!):
itself!
[[glossary]]
-include::glossary.txt[]
+GIT Glossary
+============
+
+include::glossary-content.txt[]
[[git-quick-start]]
Appendix A: Git Quick Reference
* remote example
URL: git://example.com/project.git
Tracked remote branches
- master next ...
+ master
+ next
+ ...
$ git fetch example # update branches from example
$ git branch -r # list all remote branches
-----------------------------------------------
More on recovery from repository corruption. See:
http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2
http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2
- http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2