GIT 1.0.9

If you are a long time git user/developer, you forget that to a new git
user, these words have not the same meaning as to you.

[jc: with updates from J. Bruce Fields.]

Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: Junio C Hamano <junkio@cox.net>

.gitignore

@@ -19,6 +19,7 @@ git-commit
 git-commit-tree
 git-convert-objects
 git-count-objects
+git-cvsexportcommit
 git-cvsimport
 git-daemon
 git-diff
@@ -36,10 +37,12 @@ git-get-tar-commit-id
 git-grep
 git-hash-object
 git-http-fetch
+git-http-push
 git-index-pack
 git-init-db
 git-local-fetch
 git-log
+git-lost-found
 git-ls-files
 git-ls-remote
 git-ls-tree
@@ -57,7 +60,7 @@ git-merge-stupid
 git-mktag
 git-name-rev
 git-mv
-git-octopus
+git-pack-redundant
 git-pack-objects
 git-parse-remote
 git-patch-id
@@ -70,8 +73,8 @@ git-read-tree
 git-rebase
 git-receive-pack
 git-relink
-git-rename
 git-repack
+git-repo-config
 git-request-pull
 git-reset
 git-resolve
@@ -107,6 +110,8 @@ git-verify-tag
 git-whatchanged
 git-write-tree
 git-core-*/?*
+test-date
+test-delta
 *.tar.gz
 *.dsc
 *.deb
@@ -114,3 +119,4 @@ git-core.spec
 *.exe
 libgit.a
 *.o
+*.py[co]

Documentation/.gitignore

@@ -3,3 +3,4 @@
 *.1
 *.7
 howto-index.txt
+doc.dep

Documentation/Makefile

@@ -9,6 +9,7 @@ ARTICLES += diffcore
 ARTICLES += howto-index
 ARTICLES += repository-layout
 ARTICLES += hooks
+ARTICLES += everyday
 # with their own formatting rules.
 SP_ARTICLES = glossary howto/revert-branch-rebase
 
@@ -49,22 +50,22 @@ install: man
 	$(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1)
 	$(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7)
 
-# 'include' dependencies
-$(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
-	diff-format.txt diff-options.txt
-$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
-	diff-format.txt diff-options.txt
 
-$(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
+#
-$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt
+# Determine "include::" file references in asciidoc files.
+#
+doc.dep : $(wildcard *.txt) build-docdep.perl
+	rm -f $@+ $@
+	perl ./build-docdep.perl >$@+
+	mv $@+ $@
 
-$(patsubst %,%.1,git-merge git-pull): merge-pull-opts.txt
+-include doc.dep
-$(patsubst %,%.html,git-merge git-pull): merge-pull-opts.txt
 
 git.7: ../README
 
+
 clean:
-	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html
+	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep
 
 %.html : %.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<

Documentation/build-docdep.perl

@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+
+my %include = ();
+my %included = ();
+
+for my $text (<*.txt>) {
+    open I, '<', $text || die "cannot read: $text";
+    while (<I>) {
+	if (/^include::/) {
+	    chomp;
+	    s/^include::\s*//;
+	    s/\[\]//;
+	    $include{$text}{$_} = 1;
+	    $included{$_} = 1;
+	}
+    }
+    close I;
+}
+
+# Do we care about chained includes???
+my $changed = 1;
+while ($changed) {
+    $changed = 0;
+    while (my ($text, $included) = each %include) {
+	for my $i (keys %$included) {
+	    # $text has include::$i; if $i includes $j
+	    # $text indirectly includes $j.
+	    if (exists $include{$i}) {
+		for my $j (keys %{$include{$i}}) {
+		    if (!exists $include{$text}{$j}) {
+			$include{$text}{$j} = 1;
+			$included{$j} = 1;
+			$changed = 1;
+		    }
+		}
+	    }
+	}
+    }
+}
+
+while (my ($text, $included) = each %include) {
+    if (! exists $included{$text} &&
+	(my $base = $text) =~ s/\.txt$//) {
+	my ($suffix) = '1';
+	if ($base eq 'git') {
+	    $suffix = '7'; # yuck...
+	}
+	print "$base.html $base.$suffix : ", join(" ", keys %$included), "\n";
+    }
+}

Documentation/cvs-migration.txt

@@ -138,7 +138,7 @@ mailing list archives for details).
 git has a couple of alternatives, though, that you may find sufficient
 or even superior depending on your use.  One is called "git-whatchanged"
 (for obvious reasons) and the other one is called "pickaxe" ("a tool for
-the software archeologist"). 
+the software archaeologist"). 
 
 The "git-whatchanged" script is a truly trivial script that can give you
 a good overview of what has changed in a file or a directory (or an
@@ -187,7 +187,8 @@ you would use git-rev-list and git-diff-tree like this:
 
 We have already talked about the "\--stdin" form of git-diff-tree
 command that reads the list of commits and compares each commit
-with its parents.  The git-whatchanged command internally runs
+with its parents (otherwise you should go back and read the tutorial).
+The git-whatchanged command internally runs
 the equivalent of the above command, and can be used like this:
 
 	$ git-whatchanged -p -S'if (frotz) {

Documentation/diff-format.txt

@@ -8,13 +8,13 @@ git-diff-index <tree-ish>::
         compares the <tree-ish> and the files on the filesystem.
 
 git-diff-index --cached <tree-ish>::
-        compares the <tree-ish> and the cache.
+        compares the <tree-ish> and the index.
 
 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
         compares the trees named by the two arguments.
 
 git-diff-files [<pattern>...]::
-        compares the cache and the files on the filesystem.
+        compares the index and the files on the filesystem.
 
 
 An output line is formatted this way:
@@ -47,7 +47,7 @@ That is, from the left to the right:
 . an LF or a NUL when '-z' option is used, to terminate the record.
 
 <sha1> is shown as all 0's if a file is new on the filesystem
-and it is out of sync with the cache.
+and it is out of sync with the index.
 
 Example:
 
@@ -81,7 +81,7 @@ The "diff" formatting options can be customized via the
 environment variable 'GIT_DIFF_OPTS'.  For example, if you
 prefer context diff:
 
-      GIT_DIFF_OPTS=-c git-diff-index -p $(cat .git/HEAD)
+      GIT_DIFF_OPTS=-c git-diff-index -p HEAD
 
 
 2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
@@ -104,7 +104,7 @@ where:
 The file parameters can point at the user's working file
 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 when a new file is added), or a temporary file (e.g. `old-file` in the
-cache).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
+index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 
 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
@@ -117,7 +117,7 @@ git specific extension to diff format
 What -p option produces is slightly different from the
 traditional diff format.
 
-1.   It is preceeded with a "git diff" header, that looks like
+1.   It is preceded with a "git diff" header, that looks like
      this:
 
      diff --git a/file1 b/file2

Documentation/diff-options.txt

@@ -13,6 +13,19 @@
 --name-status::
 	Show only names and status of changed files.
 
+--full-index::
+	Instead of the first handful characters, show full
+	object name of pre- and post-image blob on the "index"
+	line when generating a patch format output.	
+
+--abbrev[=<n>]::
+	Instead of showing the full 40-byte hexadecimal object
+	name in diff-raw format output and diff-tree header
+	lines, show only handful hexdigits prefix.  This is
+	independent of --full-index option above, which controls
+	the diff-patch output format.  Non default number of
+	digits can be specified with --abbrev=<n>.
+
 -B::
 	Break complete rewrite changes into pairs of delete and create.
 
@@ -50,7 +63,7 @@
 	<orderfile>, which has one shell glob pattern per line.
 
 -R::
-	Swap two inputs; that is, show differences from cache or
+	Swap two inputs; that is, show differences from index or
 	on-disk file to tree contents.
 
 For more detailed explanation on these common options, see also

Documentation/everyday.txt

@@ -0,0 +1,441 @@
+Everyday GIT With 20 Commands Or So
+===================================
+
+GIT suite has over 100 commands, and the manual page for each of
+them discusses what the command does and how it is used in
+detail, but until you know what command should be used in order
+to achieve what you want to do, you cannot tell which manual
+page to look at, and if you know that already you do not need
+the manual.
+
+Does that mean you need to know all of them before you can use
+git?  Not at all.  Depending on the role you play, the set of
+commands you need to know is slightly different, but in any case
+what you need to learn is far smaller than the full set of
+commands to carry out your day-to-day work.  This document is to
+serve as a cheat-sheet and a set of pointers for people playing
+various roles.
+
+<<Basic Repository>> commands are needed by people who has a
+repository --- that is everybody, because every working tree of
+git is a repository.
+
+In addition, <<Individual Developer (Standalone)>> commands are
+essential for anybody who makes a commit, even for somebody who
+works alone.
+
+If you work with other people, you will need commands listed in
+<<Individual Developer (Participant)>> section as well.
+
+People who play <<Integrator>> role need to learn some more
+commands in addition to the above.
+
+<<Repository Administration>> commands are for system
+administrators who are responsible to care and feed git
+repositories to support developers.
+
+
+Basic Repository[[Basic Repository]]
+------------------------------------
+
+Everybody uses these commands to feed and care git repositories.
+
+  * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a
+    new repository.
+
+  * gitlink:git-fsck-objects[1] to validate the repository.
+
+  * gitlink:git-prune[1] to garbage collect crufts in the
+    repository.
+
+  * gitlink:git-repack[1] to pack loose objects for efficiency.
+
+Examples
+~~~~~~~~
+
+Check health and remove cruft.::
++
+------------
+$ git fsck-objects <1>
+$ git prune
+$ git count-objects <2>
+$ git repack <3>
+$ git prune <4>
+
+<1> running without "--full" is usually cheap and assures the
+repository health reasonably well.
+<2> check how many loose objects there are and how much
+diskspace is wasted by not repacking.
+<3> without "-a" repacks incrementally.  repacking every 4-5MB
+of loose objects accumulation may be a good rule of thumb.
+<4> after repack, prune removes the duplicate loose objects.
+------------
+
+Repack a small project into single pack.::
++
+------------
+$ git repack -a -d <1>
+$ git prune
+
+<1> pack all the objects reachable from the refs into one pack
+and remove unneeded other packs
+------------
+
+
+Individual Developer (Standalone)[[Individual Developer (Standalone)]]
+----------------------------------------------------------------------
+
+A standalone individual developer does not exchange patches with
+other poeple, and works alone in a single repository, using the
+following commands.
+
+  * gitlink:git-show-branch[1] to see where you are.
+
+  * gitlink:git-log[1] to see what happened.
+
+  * gitlink:git-whatchanged[1] to find out where things have
+    come from.
+
+  * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch
+    branches.
+
+  * gitlink:git-add[1] and gitlink:git-update-index[1] to manage
+    the index file.
+
+  * gitlink:git-diff[1] and gitlink:git-status[1] to see what
+    you are in the middle of doing.
+
+  * gitlink:git-commit[1] to advance the current branch.
+
+  * gitlink:git-reset[1] and gitlink:git-checkout[1] (with
+    pathname parameters) to undo changes.
+
+  * gitlink:git-pull[1] with "." as the remote to merge between
+    local branches.
+
+  * gitlink:git-rebase[1] to maintain topic branches.
+
+  * gitlink:git-tag[1] to mark known point.
+
+Examples
+~~~~~~~~
+
+Extract a tarball and create a working tree and a new repository to keep track of it.::
++
+------------
+$ tar zxf frotz.tar.gz
+$ cd frotz
+$ git-init-db
+$ git add . <1>
+$ git commit -m 'import of frotz source tree.'
+$ git tag v2.43 <2>
+
+<1> add everything under the current directory.
+<2> make a lightweight, unannotated tag.
+------------
+
+Create a topic branch and develop.::
++
+------------
+$ git checkout -b alsa-audio <1>
+$ edit/compile/test
+$ git checkout -- curses/ux_audio_oss.c <2>
+$ git add curses/ux_audio_alsa.c <3>
+$ edit/compile/test
+$ git diff <4>
+$ git commit -a -s <5>
+$ edit/compile/test
+$ git reset --soft HEAD^ <6>
+$ edit/compile/test
+$ git diff ORIG_HEAD <7>
+$ git commit -a -c ORIG_HEAD <8>
+$ git checkout master <9>
+$ git pull . alsa-audio <10>
+$ git log --since='3 days ago' <11>
+$ git log v2.43.. curses/ <12>
+
+<1> create a new topic branch.
+<2> revert your botched changes in "curses/ux_audio_oss.c".
+<3> you need to tell git if you added a new file; removal and
+modification will be caught if you do "commit -a" later.
+<4> to see what changes you are committing.
+<5> commit everything as you have tested, with your sign-off.
+<6> take the last commit back, keeping what is in the working tree.
+<7> look at the changes since the premature commit we took back.
+<8> redo the commit undone in the previous step, using the message
+you originally wrote.
+<9> switch to the master branch.
+<10> merge a topic branch into your master branch
+<11> review commit logs; other forms to limit output can be
+combined and include --max-count=10 (show 10 commits), --until='2005-12-10'.
+<12> view only the changes that touch what's in curses/
+directory, since v2.43 tag.
+------------
+
+
+Individual Developer (Participant)[[Individual Developer (Participant)]]
+------------------------------------------------------------------------
+
+A developer working as a participant in a group project needs to
+learn how to communicate with others, and uses these commands in
+addition to the ones needed by a standalone developer.
+
+  * gitlink:git-clone[1] from the upstream to prime your local
+    repository.
+
+  * gitlink:git-pull[1] and gitlink:git-fetch[1] from "origin"
+    to keep up-to-date with the upstream.
+
+  * gitlink:git-push[1] to shared repository, if you adopt CVS
+    style shared repository workflow.
+
+  * gitlink:git-format-patch[1] to prepare e-mail submission, if
+    you adopt Linux kernel-style public forum workflow.
+
+Examples
+~~~~~~~~
+
+Clone the upstream and work on it.  Feed changes to upstream.::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
+$ cd my2.6
+$ edit/compile/test; git commit -a -s <1>
+$ git format-patch origin <2>
+$ git pull <3>
+$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
+$ git reset --hard ORIG_HEAD <6>
+$ git prune <7>
+$ git fetch --tags <8>
+
+<1> repeat as needed.
+<2> extract patches from your branch for e-mail submission.
+<3> "pull" fetches from "origin" by default and merges into the
+current branch.
+<4> immediately after pulling, look at the changes done upstream
+since last time we checked, only in the
+area we are interested in.
+<5> fetch from a specific branch from a specific repository and merge.
+<6> revert the pull.
+<7> garbage collect leftover objects from reverted pull.
+<8> from time to time, obtain official tags from the "origin"
+and store them under .git/refs/tags/.
+------------
+
+
+Push into another repository.::
++
+------------
+satellite$ git clone mothership:frotz/.git frotz <1>
+satellite$ cd frotz
+satellite$ cat .git/remotes/origin <2>
+URL: mothership:frotz/.git
+Pull: master:origin
+satellite$ echo 'Push: master:satellite' >>.git/remotes/origin <3>
+satellite$ edit/compile/test/commit
+satellite$ git push origin <4>
+
+mothership$ cd frotz
+mothership$ git checkout master
+mothership$ git pull . satellite <5>
+
+<1> mothership machine has a frotz repository under your home
+directory; clone from it to start a repository on the satellite
+machine.
+<2> clone creates this file by default.  It arranges "git pull"
+to fetch and store the master branch head of mothership machine
+to local "origin" branch.
+<3> arrange "git push" to push local "master" branch to
+"satellite" branch of the mothership machine.
+<4> push will stash our work away on "satellite" branch on the
+mothership machine.  You could use this as a back-up method.
+<5> on mothership machine, merge the work done on the satellite
+machine into the master branch.
+------------
+
+Branch off of a specific tag.::
++
+------------
+$ git checkout -b private2.6.14 v2.6.14 <1>
+$ edit/compile/test; git commit -a
+$ git checkout master
+$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
+  git am -3 -k <2>
+
+<1> create a private branch based on a well known (but somewhat behind)
+tag.
+<2> forward port all changes in private2.6.14 branch to master branch
+without a formal "merging".
+------------
+
+
+Integrator[[Integrator]]
+------------------------
+
+A fairly central person acting as the integrator in a group
+project receives changes made by others, reviews and integrates
+them and publishes the result for others to use, using these
+commands in addition to the ones needed by participants.
+
+  * gitlink:git-am[1] to apply patches e-mailed in from your
+    contributors.
+
+  * gitlink:git-pull[1] to merge from your trusted lieutenants.
+
+  * gitlink:git-format-patch[1] to prepare and send suggested
+    alternative to contributors.
+
+  * gitlink:git-revert[1] to undo botched commits.
+
+  * gitlink:git-push[1] to publish the bleeding edge.
+
+
+Examples
+~~~~~~~~
+
+My typical GIT day.::
++
+------------
+$ git status <1>
+$ git show-branch <2>
+$ mailx <3>
+& s 2 3 4 5 ./+to-apply
+& s 7 8 ./+hold-linus
+& q
+$ git checkout master
+$ git am -3 -i -s -u ./+to-apply <4>
+$ compile/test
+$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
+$ git checkout topic/one && git rebase master <6>
+$ git checkout pu && git reset --hard master <7>
+$ git pull . topic/one topic/two && git pull . hold/linus <8>
+$ git checkout maint
+$ git cherry-pick master~4 <9>
+$ compile/test
+$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10>
+$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
+$ git push ko <12>
+$ git push ko v0.99.9x <13>
+
+<1> see what I was in the middle of doing, if any.
+<2> see what topic branches I have and think about how ready
+they are.
+<3> read mails, save ones that are applicable, and save others
+that are not quite ready.
+<4> apply them, interactively, with my sign-offs.
+<5> create topic branch as needed and apply, again with my
+sign-offs. 
+<6> rebase internal topic branch that has not been merged to the
+master, nor exposed as a part of a stable branch.
+<7> restart "pu" every time from the master.
+<8> and bundle topic branches still cooking.
+<9> backport a critical fix.
+<10> create a signed tag.
+<11> make sure I did not accidentally rewind master beyond what I
+already pushed out.  "ko" shorthand points at the repository I have
+at kernel.org, and looks like this:
+    $ cat .git/remotes/ko
+    URL: kernel.org:/pub/scm/git/git.git
+    Pull: master:refs/tags/ko-master
+    Pull: maint:refs/tags/ko-maint
+    Push: master
+    Push: +pu
+    Push: maint
+In the output from "git show-branch", "master" should have
+everything "ko-master" has.
+<12> push out the bleeding edge.
+<13> push the tag out, too.
+------------
+
+
+Repository Administration[[Repository Administration]]
+------------------------------------------------------
+
+A repository administrator uses the following tools to set up
+and maintain access to the repository by developers.
+
+  * gitlink:git-daemon[1] to allow anonymous download from
+    repository.
+
+  * gitlink:git-shell[1] can be used as a 'restricted login shell'
+    for shared central repository users.
+
+link:howto/update-hook-example.txt[update hook howto] has a good
+example of managing a shared central repository.
+
+
+Examples
+~~~~~~~~
+
+Run git-daemon to serve /pub/scm from inetd.::
++
+------------
+$ grep git /etc/inet.conf
+git	stream	tcp	nowait	nobody \
+  /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+------------
++
+The actual configuration line should be on one line.
+
+Give push/pull only access to developers.::
++
+------------
+$ grep git /etc/passwd <1>
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
+david:x:1003:1003::/home/david:/usr/bin/git-shell
+$ grep git /etc/shells <2>
+/usr/bin/git-shell
+
+<1> log-in shell is set to /usr/bin/git-shell, which does not
+allow anything but "git push" and "git pull".  The users should
+get an ssh access to the machine.
+<2> in many distributions /etc/shells needs to list what is used
+as the login shell.
+------------
+
+CVS-style shared repository.::
++
+------------
+$ grep git /etc/group <1>
+git:x:9418:alice,bob,cindy,david
+$ cd /home/devo.git
+$ ls -l <2>
+  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
+  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
+  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
+  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
+  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
+  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
+$ ls -l hooks/update <3>
+  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
+$ cat info/allowed-users <4>
+refs/heads/master	alice\|cindy
+refs/heads/doc-update	bob
+refs/tags/v[0-9]*	david
+
+<1> place the developers into the same git group.
+<2> and make the shared repository writable by the group.
+<3> use update-hook example by Carl from Documentation/howto/
+for branch policy control.
+<4> alice and cindy can push into master, only bob can push into doc-update.
+david is the release manager and is the only person who can
+create and push version tags.
+------------
+
+HTTP server to support dumb protocol transfer.::
++
+------------
+dev$ git update-server-info <1>
+dev$ ftp user@isp.example.com <2>
+ftp> cp -r .git /home/user/myproject.git
+
+<1> make sure your info/refs and objects/info/packs are up-to-date
+<2> upload to public HTTP server hosted by your ISP.
+------------

Documentation/fetch-options.txt

@@ -0,0 +1,24 @@
+-a, \--append::
+	Append ref names and object names of fetched refs to the
+	existing contents of `.git/FETCH_HEAD`.  Without this
+	option old data in `.git/FETCH_HEAD` will be overwritten.
+
+-f, \--force::
+	When `git-fetch` is used with `<rbranch>:<lbranch>`
+	refspec, it refuses to update the local branch
+	`<lbranch>` unless the remote branch `<rbranch>` it
+	fetches is a descendant of `<lbranch>`.  This option
+	overrides that check.
+
+-t, \--tags::
+	By default, the git core utilities will not fetch and store
+	tags under the same name as the remote repository;  ask it
+	to do so using `--tags`.  Using this option will bound the
+	list of objects pulled to the remote tags.  Commits in branches
+	beyond the tags will be ignored.
+
+-u, \--update-head-ok::
+	By default `git-fetch` refuses to update the head which
+	corresponds to the current branch.  This flag disables the
+	check.  Note that fetching into the current branch will not
+	update the index and working directory, so use it with care.

Documentation/git-add.txt

@@ -31,7 +31,7 @@ DISCUSSION
 ----------
 
 The list of <file> given to the command is fed to `git-ls-files`
-command to list files that are not registerd in the index and
+command to list files that are not registered in the index and
 are not ignored/excluded by `$GIT_DIR/info/exclude` file or
 `.gitignore` file in each directory.  This means two things:
 

Documentation/git-am.txt

@@ -8,8 +8,9 @@ git-am - Apply a series of patches in a mailbox
 
 SYNOPSIS
 --------
-'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--3way] <mbox>...
+[verse]
-'git-am' [--skip]
+'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] <mbox>...
+'git-am' [--skip | --resolved]
 
 DESCRIPTION
 -----------
@@ -28,9 +29,13 @@ OPTIONS
 	area to store extracted patches.
 
 --utf8, --keep::
-	Pass `--utf8` and `--keep` flags to `git-mailinfo` (see
+	Pass `-u` and `-k` flags to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
+--binary::
+	Pass `--allow-binary-replacement` flag to `git-apply`
+	(see gitlink:git-apply[1]).
+
 --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
@@ -44,6 +49,13 @@ OPTIONS
 --interactive::
 	Run interactively, just like git-applymbox.
 
+--resolved::
+	After a patch failure (e.g. attempting to apply
+	conflicting patch), the user has applied it by hand and
+	the index file stores the result of the application.
+	Make a commit using the authorship and commit log
+	extracted from the e-mail message and the current index
+	file, and continue.
 
 DISCUSSION
 ----------
@@ -56,12 +68,9 @@ recover from this in one of two ways:
 . skip the current one by re-running the command with '--skip'
   option.
 
-. hand resolve the conflict in the working directory, run 'git
+. hand resolve the conflict in the working directory, and update
-  diff HEAD' to extract the merge result into a patch form and
+  the index file to bring it in a state that the patch should
-  replacing the patch in .dotest/patch file.  After doing this,
+  have produced.  Then run the command with '--resolved' option.
-  run `git-reset --hard HEAD` to bring the working tree to the
-  state before half-applying the patch, then re-run the command
-  without any options.
 
 The command refuses to process new mailboxes while `.dotest`
 directory exists, so if you decide to start over from scratch,

Documentation/git-apply.txt

@@ -8,7 +8,10 @@ git-apply - Apply patch on a git index file and a work tree
 
 SYNOPSIS
 --------
-'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--index-info] [-z] [<patch>...]
+[verse]
+'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply]
+	  [--no-add] [--index-info] [--allow-binary-replacement] [-z]
+	  [<patch>...]
 
 DESCRIPTION
 -----------
@@ -72,6 +75,23 @@ OPTIONS
 	patch.  Give this flag after those flags to also apply
 	the patch.
 
+--no-add::
+	When applying a patch, ignore additions made by the
+	patch.  This can be used to extract common part between
+	two files by first running `diff` on them and applying
+	the result with this option, which would apply the
+	deletion part but not addition part.
+
+--allow-binary-replacement::
+	When applying a patch, which is a git-enhanced patch
+	that was prepared to record the pre- and post-image object
+	name in full, and the path being patched exactly matches
+	the object the patch applies to (i.e. "index" line's
+	pre-image object name is what is in the working tree),
+	and the post-image object is available in the object
+	database, use the post-image object as the patch
+	result.  This allows binary files to be patched in a
+	very limited way.
 
 Author
 ------

Documentation/git-archimport.txt

@@ -8,14 +8,15 @@ git-archimport - Import an Arch repository into git
 
 SYNOPSIS
 --------
-`git-archimport` [ -h ] [ -v ] [ -T ] [ -t tempdir ] 
+[verse]
-                 <archive/branch> [ <archive/branch> ]
+`git-archimport` [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]
+               <archive/branch> [ <archive/branch> ]
 
 DESCRIPTION
 -----------
 Imports a project from one or more Arch repositories. It will follow branches
 and repositories within the namespaces defined by the <archive/branch>
-parameters suppplied. If it cannot find the remote branch a merge comes from
+parameters supplied. If it cannot find the remote branch a merge comes from
 it will just import it as a regular commit. If it can find it, it will mark it 
 as a merge whenever possible (see discussion below). 
 
@@ -63,6 +64,26 @@ OPTIONS
 	Many tags. Will create a tag for every commit, reflecting the commit 
 	name in the Arch repository.
 
+-f::
+	Use the fast patchset import strategy.  This can be significantly
+	faster for large trees, but cannot handle directory renames or
+	permissions changes.  The default strategy is slow and safe.
+
+-o::
+	Use this for compatibility with old-style branch names used by
+	earlier versions of git-archimport.  Old-style branch names
+	were category--branch, whereas new-style branch names are
+	archive,category--branch--version.
+
+-D <depth>::
+	Follow merge ancestry and attempt to import trees that have been
+	merged from.  Specify a depth greater than 1 if patch logs have been
+	pruned.
+
+-a::
+	Attempt to auto-register archives at http://mirrors.sourcecontrol.net
+	This is particularly useful with the -D option.
+
 -t <tmpdir>::
 	Override the default tempdir.
 

Documentation/git-bisect.txt

@@ -8,16 +8,21 @@ git-bisect - Find the change that introduced a bug
 
 SYNOPSIS
 --------
-'git bisect' start
+'git bisect' <subcommand> <options> 
-'git bisect' bad <rev>
-'git bisect' good <rev>
-'git bisect' reset [<branch>]
-'git bisect' visualize
-'git bisect' replay <logfile>
-'git bisect' log
 
 DESCRIPTION
 -----------
+The command takes various subcommands, and different options
+depending on the subcommand:
+
+ git bisect start [<paths>...]
+ git bisect bad <rev>
+ git bisect good <rev>
+ git bisect reset [<branch>]
+ git bisect visualize
+ git bisect replay <logfile>
+ git bisect log
+
 This command uses 'git-rev-list --bisect' option to help drive
 the binary search process to find which change introduced a bug,
 given an old "good" commit object name and a later "bad" commit
@@ -26,10 +31,10 @@ object name.
 The way you use it is:
 
 ------------------------------------------------
-git bisect start
+$ git bisect start
-git bisect bad			# Current version is bad
+$ git bisect bad			# Current version is bad
-git bisect good v2.6.13-rc2	# v2.6.13-rc2 was the last version
+$ git bisect good v2.6.13-rc2		# v2.6.13-rc2 was the last version
-				# tested that was good
+					# tested that was good
 ------------------------------------------------
 
 When you give at least one bad and one good versions, it will
@@ -43,7 +48,7 @@ and check out the state in the middle. Now, compile that kernel, and boot
 it. Now, let's say that this booted kernel works fine, then just do
 
 ------------------------------------------------
-git bisect good			# this one is good
+$ git bisect good			# this one is good
 ------------------------------------------------
 
 which will now say
@@ -62,7 +67,7 @@ kernel rev in "refs/bisect/bad".
 Oh, and then after you want to reset to the original head, do a
 
 ------------------------------------------------
-git bisect reset
+$ git bisect reset
 ------------------------------------------------
 
 to get back to the master branch, instead of being in one of the bisection
@@ -72,7 +77,9 @@ not using some old bisection branch).
 
 During the bisection process, you can say
 
-	git bisect visualize
+------------
+$ git bisect visualize
+------------
 
 to see the currently remaining suspects in `gitk`.
 
@@ -80,11 +87,40 @@ The good/bad input is logged, and `git bisect
 log` shows what you have done so far.  You can truncate its
 output somewhere and save it in a file, and run
 
-	git bisect replay that-file
+------------
+$ git bisect replay that-file
+------------
 
 if you find later you made a mistake telling good/bad about a
 revision.
 
+If in a middle of bisect session, you know what the bisect
+suggested to try next is not a good one to test (e.g. the change
+the commit introduces is known not to work in your environment
+and you know it does not have anything to do with the bug you
+are chasing), you may want to find a near-by commit and try that
+instead.  It goes something like this:
+
+------------
+$ git bisect good/bad			# previous round was good/bad.
+Bisecting: 337 revisions left to test after this
+$ git bisect visualize			# oops, that is uninteresting.
+$ git reset --hard HEAD~3		# try 3 revs before what
+					# was suggested
+------------
+
+Then compile and test the one you chose to try.  After that,
+tell bisect what the result was as usual.
+
+You can further cut down the number of trials if you know what
+part of the tree is involved in the problem you are tracking
+down, by giving paths parameters when you say `bisect start`,
+like this:
+
+------------
+$ git bisect start arch/i386 include/asm-i386
+------------
+
 
 Author
 ------

Documentation/git-branch.txt

@@ -3,11 +3,11 @@ git-branch(1)
 
 NAME
 ----
-git-branch - Create a new branch.
+git-branch - Create a new branch, or remove an old one.
 
 SYNOPSIS
 --------
-'git-branch' [<branchname> [start-point]]
+'git-branch' [-d | -D] [<branchname> [start-point]]
 
 DESCRIPTION
 -----------
@@ -19,11 +19,44 @@ created, otherwise it will be created at the current HEAD.
 
 OPTIONS
 -------
+-d::
+	Delete a branch. The branch must be fully merged.
+
+-D::
+	Delete a branch irrespective of its index status.
+
 <branchname>::
-	The name of the branch to create.
+	The name of the branch to create or delete.
 
 start-point::
-	Where to create the branch; defaults to HEAD.
+	Where to create the branch; defaults to HEAD. This
+	option has no meaning with -d and -D.
+
+
+Examples
+~~~~~~~~
+
+Start development off of a know tag::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ git branch my2.6.14 v2.6.14 <1>
+$ git checkout my2.6.14
+
+<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14".
+------------
+
+Delete unneeded branch::
++
+------------
+$ git clone git://git.kernel.org/.../git.git my.git
+$ cd my.git
+$ git branch -D todo <1>
+
+<1> delete todo branch even if the "master" branch does not have all
+commits from todo branch.
+------------
 
 Author
 ------

Documentation/git-cat-file.txt

@@ -8,7 +8,7 @@ git-cat-file - Provide content or type information for repository objects
 
 SYNOPSIS
 --------
-'git-cat-file' (-t | -s | <type>) <object>
+'git-cat-file' [-t | -s | -e | <type>] <object>
 
 DESCRIPTION
 -----------
@@ -29,6 +29,10 @@ OPTIONS
 	Instead of the content, show the object size identified by
 	<object>.
 
+-e::
+	Suppress all output; instead exit with zero status if <object>
+	exists and is a valid object.
+
 <type>::
 	Typically this matches the real type of <object> but asking
 	for a type that can trivially be dereferenced from the given
@@ -39,8 +43,11 @@ OPTIONS
 
 OUTPUT
 ------
-If '-t' is specified, one of the <type>.  If '-s' is specified,
+If '-t' is specified, one of the <type>.
-the size of the <object> in bytes.
+
+If '-s' is specified, the size of the <object> in bytes.
+
+If '-e' is specified, no output.
 
 Otherwise the raw (though uncompressed) contents of the <object> will
 be returned.

Documentation/git-check-ref-format.txt

@@ -26,13 +26,15 @@ imposes the following rules on how refs are named:
 
 . It cannot have ASCII control character (i.e. bytes whose
   values are lower than \040, or \177 `DEL`), space, tilde `~`,
-  caret `{caret}`, or colon `:` anywhere;
+  caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`,
+  or open bracket `[` anywhere;
 
 . It cannot end with a slash `/`.
 
 These rules makes it easy for shell script based tools to parse
-refnames, and also avoids ambiguities in certain refname
+refnames, pathname expansion by the shell when a refname is used
-expressions (see gitlink:git-rev-parse[1]).  Namely:
+unquoted (by mistake), and also avoids ambiguities in certain
+refname expressions (see gitlink:git-rev-parse[1]).  Namely:
 
 . double-dot `..` are often used as in `ref1..ref2`, and in some
   context this notation means `{caret}ref1 ref2` (i.e. not in

Documentation/git-checkout-index.txt

@@ -3,36 +3,37 @@ git-checkout-index(1)
 
 NAME
 ----
-git-checkout-index - Copy files from the cache to the working directory
+git-checkout-index - Copy files from the index to the working directory
 
 
 SYNOPSIS
 --------
+[verse]
 'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
-	           [--] <file>...
+		   [--stage=<number>] [--] <file>...
 
 DESCRIPTION
 -----------
-Will copy all files listed from the cache to the working directory
+Will copy all files listed from the index to the working directory
 (not overwriting existing files).
 
 OPTIONS
 -------
--u::
+-u|--index::
 	update stat information for the checked out entries in
-	the cache file.
+	the index file.
 
--q::
+-q|--quiet::
-	be quiet if files exist or are not in the cache
+	be quiet if files exist or are not in the index
 
--f::
+-f|--force::
 	forces overwrite of existing files
 
--a::
+-a|--all::
-	checks out all files in the cache.  Cannot be used
+	checks out all files in the index.  Cannot be used
 	together with explicit filenames.
 
--n::
+-n|--no-create::
 	Don't checkout new files, only refresh files already checked
 	out.
 
@@ -40,58 +41,80 @@ OPTIONS
 	When creating files, prepend <string> (usually a directory
 	including a trailing /)
 
+--stage=<number>::
+	Instead of checking out unmerged entries, copy out the
+	files from named stage.  <number> must be between 1 and 3.
+
 --::
 	Do not interpret any more arguments as options.
 
 The order of the flags used to matter, but not anymore.
 
-Just doing "git-checkout-index" does nothing. You probably meant
+Just doing `git-checkout-index` does nothing. You probably meant
-"git-checkout-index -a". And if you want to force it, you want
+`git-checkout-index -a`. And if you want to force it, you want
-"git-checkout-index -f -a".
+`git-checkout-index -f -a`.
 
 Intuitiveness is not the goal here. Repeatability is. The reason for
-the "no arguments means no work" thing is that from scripts you are
+the "no arguments means no work" behavior is that from scripts you are
-supposed to be able to do things like:
+supposed to be able to do:
 
-	find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
+$ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
 
 which will force all existing `*.h` files to be replaced with their
 cached copies. If an empty command line implied "all", then this would
-force-refresh everything in the cache, which was not the point.
+force-refresh everything in the index, which was not the point.
 
-To update and refresh only the files already checked out:
+The `--` is just a good idea when you know the rest will be filenames;
+it will prevent problems with a filename of, for example,  `-a`.
+Using `--` is probably a good policy in scripts.
 
-        git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
 
-Oh, and the "--" is just a good idea when you know the rest will be
+EXAMPLES
-filenames. Just so that you wouldn't have a filename of "-a" causing
+--------
-problems (not possible in the above example, but get used to it in
+To update and refresh only the files already checked out::
-scripting!).
++
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
 
-The prefix ability basically makes it trivial to use
+Using `git-checkout-index` to "export an entire tree"::
-git-checkout-index as an "export as tree" function. Just read the
+	The prefix ability basically makes it trivial to use
-desired tree into the index, and do a
+	`git-checkout-index` as an "export as tree" function.
-
+	Just read the desired tree into the index, and do:
-        git-checkout-index --prefix=git-export-dir/ -a
++
-
+----------------
-and git-checkout-index will "export" the cache into the specified
+$ git-checkout-index --prefix=git-export-dir/ -a
+----------------
++
+`git-checkout-index` will "export" the index into the specified
 directory.
++
+The final "/" is important. The exported name is literally just
+prefixed with the specified string.  Contrast this with the
+following example.
 
-NOTE The final "/" is important. The exported name is literally just
+Export files with a prefix::
-prefixed with the specified string, so you can also do something like
++
+----------------
+$ git-checkout-index --prefix=.merged- Makefile
+----------------
++
+This will check out the currently cached copy of `Makefile`
+into the file `.merged-Makefile`.
 
-    git-checkout-index --prefix=.merged- Makefile
-
-to check out the currently cached copy of `Makefile` into the file
-`.merged-Makefile`
 
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>
 
+
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves,
+Junio C Hamano and the git-list <git@vger.kernel.org>.
+
 
 GIT
 ---

Documentation/git-checkout.txt

@@ -50,10 +50,14 @@ the `Makefile` to two revisions back, deletes hello.c by
 mistake, and gets it back from the index.
 
 ------------
-$ git checkout master
+$ git checkout master <1>
-$ git checkout master~2 Makefile
+$ git checkout master~2 Makefile <2>
 $ rm -f hello.c
-$ git checkout hello.c
+$ git checkout hello.c <3>
+
+<1> switch branch
+<2> take out a file out of other commit
+<3> or "git checkout -- hello.c", as in the next example.
 ------------
 
 If you have an unfortunate branch that is named `hello.c`, the

Documentation/git-cherry-pick.txt

@@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit.
 
 SYNOPSIS
 --------
-'git-cherry-pick' [-n] [-r] <commit>
+'git-cherry-pick' [--edit] [-n] [-r] <commit>
 
 DESCRIPTION
 -----------
@@ -20,15 +20,19 @@ OPTIONS
 <commit>::
 	Commit to cherry-pick.
 
--r::
+-e|--edit::
+	With this option, `git-cherry-pick` will let you edit the commit
+	message prior committing.
+
+-r|--replay::
 	Usually the command appends which commit was
 	cherry-picked after the original commit message when
 	making a commit.  This option, '--replay', causes it to
 	use the original commit message intact.  This is useful
 	when you are reordering the patches in your private tree
-	before publishing, and is used by 'git rebase'.
+	before publishing.
 
--n::
+-n|--no-commit::
 	Usually the command automatically creates a commit with
 	a commit log message stating which commit was
 	cherry-picked.  This flag applies the change necessary

Documentation/git-clone-pack.txt

@@ -43,7 +43,11 @@ OPTIONS
 	The heads to update.  This is relative to $GIT_DIR
 	(e.g. "HEAD", "refs/heads/master").  When unspecified,
 	all heads are updated to match the remote repository.
-
++
+Usually all the refs from existing repository are stored
+under the same name in the new repository.  Giving explicit
+<head> arguments instead writes the object names and refs to
+the standard output, just like get-fetch-pack does.
 
 Author
 ------

Documentation/git-clone.txt

@@ -8,11 +8,28 @@ git-clone - Clones a repository.
 
 SYNOPSIS
 --------
-'git-clone' [-l [-s]] [-q] [-n] [-u <upload-pack>] <repository> <directory>
+[verse]
+'git-clone' [-l [-s]] [-q] [-n] [-u <upload-pack>]
+	  <repository> [<directory>]
 
 DESCRIPTION
 -----------
-Clones a repository into a newly created directory.
+Clones a repository into a newly created directory.  All remote
+branch heads are copied under `$GIT_DIR/refs/heads/`, except
+that the remote `master` is also copied to `origin` branch.
+
+In addition, `$GIT_DIR/remotes/origin` file is set up to have
+this line:
+
+	Pull: master:origin
+
+This is to help the typical workflow of working off of the
+remote `master` branch.  Every time `git pull` without argument
+is run, the progress on the remote `master` branch is tracked by
+copying it into the local `origin` branch, and merged into the
+branch you are currently working on.  Remote branches other than
+`master` are also added there to be tracked.
+
 
 OPTIONS
 -------
@@ -28,9 +45,10 @@ OPTIONS
 --shared::
 -s::
 	When the repository to clone is on the local machine,
-	instead of using hard links automatically setup
+	instead of using hard links, automatically setup
 	.git/objects/info/alternatives to share the objects
-	with the source repository
+	with the source repository.  The resulting repository
+	starts out without any object of its own.
 
 --quiet::
 -q::
@@ -49,21 +67,43 @@ OPTIONS
 
 <repository>::
 	The (possibly remote) repository to clone from.  It can
-	be an "rsync://host/dir" URL, an "http://host/dir" URL,
+	be any URL git-fetch supports.
-	or [<host>:]/dir notation that is used by 'git-clone-pack'.
-	Currently http transport is not supported.
 
 <directory>::
-	The name of a new directory to be cloned into.  It is an
+	The name of a new directory to clone into.  The	"humanish"
-	error to specify an existing directory.
+	part of the source repository is used if no directory is
+	explicitly given ("repo" for "/path/to/repo.git" and "foo"
+	for "host.xz:foo/.git").  Cloning into an existing directory
+	is not allowed.
+
+Examples
+~~~~~~~~
+
+Clone from upstream::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ make
+------------
+
+
+Make a local clone that borrows from the current directory, without checking things out::
++
+------------
+$ git clone -l -s -n . ../copy
+$ cd copy
+$ git show-branch
+------------
 
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>
 
+
 Documentation
 --------------
-Documentation by Junio C Hamano.
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 
 GIT

Documentation/git-commit-tree.txt

@@ -8,7 +8,7 @@ git-commit-tree - Creates a new commit object
 
 SYNOPSIS
 --------
-'git-commit-tree' <tree> [-p <parent commit>]\   < changelog
+'git-commit-tree' <tree> [-p <parent commit>]\* < changelog
 
 DESCRIPTION
 -----------
@@ -26,8 +26,9 @@ to get there.
 
 Normally a commit would identify a new "HEAD" state, and while git
 doesn't care where you save the note about that state, in practice we
-tend to just write the result to the file `.git/HEAD`, so that we can
+tend to just write the result to the file that is pointed at by
-always see what the last committed state was.
+`.git/HEAD`, so that we can always see what the last committed
+state was.
 
 OPTIONS
 -------
@@ -59,7 +60,8 @@ either `.git/config` file, or using the following environment variables.
 
 (nb "<", ">" and "\n"s are stripped)
 
-In `.git/config` file, the following items are used:
+In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and
+GIT_AUTHOR_EMAIL:
 
 	[user]
 		name = "Your Name"

Documentation/git-commit.txt

@@ -7,7 +7,9 @@ git-commit - Record your changes
 
 SYNOPSIS
 --------
-'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] [-e] <file>...
+[verse]
+'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
+	   [-e] [--] <file>...
 
 DESCRIPTION
 -----------
@@ -22,7 +24,7 @@ information.
 
 OPTIONS
 -------
--a::
+-a|--all::
 	Update all paths in the index file.
 
 -c or -C <commit>::
@@ -39,27 +41,37 @@ OPTIONS
 -m <msg>::
 	Use the given <msg> as the commit message.
 
--s::
+-s|--signoff::
 	Add Signed-off-by line at the end of the commit message.
 
--v::
+-v|--verify::
 	Look for suspicious lines the commit introduces, and
 	abort committing if there is one.  The definition of
 	'suspicious lines' is currently the lines that has
 	trailing whitespaces, and the lines whose indentation
 	has a SP character immediately followed by a TAB
-	character.
+	character.  This is the default.
 
--e::
+-n|--no-verify::
+	The opposite of `--verify`.
+
+-e|--edit::
 	The message taken from file with `-F`, command line with
 	`-m`, and from file with `-C` are usually used as the
 	commit log message unmodified.  This option lets you
 	further edit the message taken from these sources.
 
+--::
+	Do not interpret any more arguments as options.
+
 <file>...::
 	Update specified paths in the index file before committing.
 
 
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and

Documentation/git-cvsexportcommit.txt

@@ -0,0 +1,55 @@
+git-cvsexportcommit(1)
+======================
+
+NAME
+----
+git-cvsexportcommit - Export a commit to a CVS checkout
+
+
+SYNOPSIS
+--------
+'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [PARENTCOMMIT] COMMITID
+
+
+DESCRIPTION
+-----------
+Exports a commit from GIT to a CVS checkout, making it easier
+to merge patches from a git repository into a CVS repository. 
+
+Execute it from the root of the CVS working copy. GIT_DIR must be defined. 
+
+It does its best to do the safe thing, it will check that the files are 
+unchanged and up to date in the CVS checkout, and it will not autocommit 
+by default.
+
+Supports file additions, removals, and commits that affect binary files.
+
+If the commit is a merge commit, you must tell git-cvsapplycommit what parent
+should the changeset be done against. 
+
+OPTIONS
+-------
+
+-c::
+	Commit automatically if the patch applied cleanly. It will not
+	commit if any hunks fail to apply or there were other problems.
+
+-p::
+	Be pedantic (paranoid) when applying patches. Invokes patch with 
+	--fuzz=0
+
+-v::
+	Verbose.
+
+Author
+------
+Written by Martin Langhoff <martin@catalyst.net.nz>
+
+Documentation
+--------------
+Documentation by Martin Langhoff <martin@catalyst.net.nz>
+
+GIT
+---
+Part of the gitlink:git[7] suite
+

Documentation/git-cvsimport.txt

@@ -8,10 +8,10 @@ git-cvsimport - Import a CVS repository into git
 
 SYNOPSIS
 --------
-'git-cvsimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ]
+[verse]
-			[ -d <CVSROOT> ] [ -p <options-for-cvsps> ]
+'git-cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-s <subst>]
-			[ -C <git_repository> ] [ -i ] [ -P <file> ] [ -k ]
+	      [-p <options-for-cvsps>] [-C <git_repository>] [-i] [-P <file>]
-			[ -s <subst> ] [ -m ] [ -M regex ] [ <CVS_module> ]
+	      [-m] [-M regex] [<CVS_module>]
 
 
 DESCRIPTION
@@ -35,7 +35,7 @@ OPTIONS
 
 -i::
 	Import-only: don't perform a checkout after importing.  This option
-	ensures the working directory and cache remain untouched and will
+	ensures the working directory and index remain untouched and will
 	not create them if they do not exist.
 
 -k::
@@ -60,7 +60,7 @@ the old cvs2git tool.
 +
 If you need to pass multiple options, separate them with a comma.
 
--P:: <cvsps-output-file>
+-P <cvsps-output-file>::
 	Instead of calling cvsps, read the provided cvsps output file. Useful
 	for debugging or when cvsps is being handled outside cvsimport.
 

Documentation/git-daemon.txt

@@ -7,8 +7,9 @@ git-daemon - A really simple server for git repositories.
 
 SYNOPSIS
 --------
+[verse]
 'git-daemon' [--verbose] [--syslog] [--inetd | --port=n] [--export-all]
-             [--timeout=n] [--init-timeout=n] [directory...]
+           [--timeout=n] [--init-timeout=n] [--strict-paths] [directory...]
 
 DESCRIPTION
 -----------
@@ -29,13 +30,19 @@ This is ideally suited for read-only updates, ie pulling from git repositories.
 
 OPTIONS
 -------
+--strict-paths::
+	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
+	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
+	git-daemon will refuse to start when this option is enabled and no
+	whitelist is specified.
+
 --export-all::
 	Allow pulling from all directories that look like GIT repositories
-	(have the 'objects' subdirectory and a 'HEAD' file), even if they
+	(have the 'objects' and 'refs' subdirectories), even if they
 	do not have the 'git-daemon-export-ok' file.
 
 --inetd::
-	Have the server run as an inetd service.
+	Have the server run as an inetd service. Implies --syslog.
 
 --port::
 	Listen on an alternative port.
@@ -57,9 +64,15 @@ OPTIONS
 --verbose::
 	Log details about the incoming connections and requested files.
 
+<directory>::
+	A directory to add to the whitelist of allowed directories. Unless
+	--strict-paths is specified this will also include subdirectories
+	of each named directory.
+
 Author
 ------
-Written by Linus Torvalds <torvalds@osdl.org> and YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org>
+Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
+<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
 
 Documentation
 --------------

Documentation/git-diff-files.txt

@@ -3,7 +3,7 @@ git-diff-files(1)
 
 NAME
 ----
-git-diff-files - Compares files in the working tree and the cache
+git-diff-files - Compares files in the working tree and the index
 
 
 SYNOPSIS
@@ -12,15 +12,24 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Compares the files in the working tree and the cache.  When paths
+Compares the files in the working tree and the index.  When paths
 are specified, compares only those named paths.  Otherwise all
-entries in the cache are compared.  The output format is the
+entries in the index are compared.  The output format is the
 same as "git-diff-index" and "git-diff-tree".
 
 OPTIONS
 -------
 include::diff-options.txt[]
 
+-1 -2 -3 or --base --ours --theirs, and -0::
+	Diff against the "base" version, "our branch" or "their
+	branch" respectively.  With these options, diffs for
+	merged entries are not shown.
++
+The default is to diff against our branch (-2) and the 
+cleanly resolved paths.  The option -0 can be given to
+omit diff output for unmerged entries and just show "Unmerged".
+
 -q::
 	Remain silent even on nonexisting files
 

Documentation/git-diff-index.txt

@@ -3,7 +3,7 @@ git-diff-index(1)
 
 NAME
 ----
-git-diff-index - Compares content and mode of blobs between the cache and repository
+git-diff-index - Compares content and mode of blobs between the index and repository
 
 
 SYNOPSIS
@@ -13,10 +13,10 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Compares the content and mode of the blobs found via a tree
-object with the content of the current cache and, optionally
+object with the content of the current index and, optionally
 ignoring the stat state of the file on disk.  When paths are
 specified, compares only those named paths.  Otherwise all
-entries in the cache are compared.
+entries in the index are compared.
 
 OPTIONS
 -------
@@ -49,22 +49,22 @@ Cached Mode
 -----------
 If '--cached' is specified, it allows you to ask:
 
-	show me the differences between HEAD and the current cache
+	show me the differences between HEAD and the current index
 	contents (the ones I'd write with a "git-write-tree")
 
 For example, let's say that you have worked on your working directory, updated
-some files in the cache and are ready to commit. You want to see eactly
+some files in the index and are ready to commit. You want to see exactly
 *what* you are going to commit is without having to write a new tree
 object and compare it that way, and to do that, you just do
 
-	git-diff-index --cached $(cat .git/HEAD)
+	git-diff-index --cached HEAD
 
 Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
 done an "git-update-index" to make that effective in the index file.
 "git-diff-files" wouldn't show anything at all, since the index file
 matches my working directory. But doing a "git-diff-index" does:
 
-  torvalds@ppc970:~/git> git-diff-index --cached $(cat .git/HEAD)
+  torvalds@ppc970:~/git> git-diff-index --cached HEAD
   -100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
   +100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c
 
@@ -92,13 +92,13 @@ which is obviously a very useful question too, since that tells you what
 you *could* commit. Again, the output matches the "git-diff-tree -r"
 output to a tee, but with a twist.
 
-The twist is that if some file doesn't match the cache, we don't have
+The twist is that if some file doesn't match the index, we don't have
 a backing store thing for it, and we use the magic "all-zero" sha1 to
 show that. So let's say that you have edited `kernel/sched.c`, but
 have not actually done a "git-update-index" on it yet - there is no
 "object" associated with the new state, and you get:
 
-  torvalds@ppc970:~/v2.6/linux> git-diff-index $(cat .git/HEAD )
+  torvalds@ppc970:~/v2.6/linux> git-diff-index HEAD
   *100644->100664 blob    7476bb......->000000......      kernel/sched.c
 
 ie it shows that the tree has changed, and that `kernel/sched.c` has is
@@ -110,7 +110,7 @@ NOTE: As with other commands of this type, "git-diff-index" does not
 actually look at the contents of the file at all. So maybe
 `kernel/sched.c` hasn't actually changed, and it's just that you
 touched it. In either case, it's a note that you need to
-"git-upate-cache" it to make the cache be in sync.
+"git-update-index" it to make the index be in sync.
 
 NOTE: You can have a mixture of files show up as "has been updated"
 and "is still dirty in the working directory" together. You can always

Documentation/git-diff-tree.txt

@@ -8,7 +8,9 @@ git-diff-tree - Compares the content and mode of blobs found via two tree object
 
 SYNOPSIS
 --------
-'git-diff-tree' [--stdin] [-m] [-s] [-v] [--pretty] [-t] [-r] [--root] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]
+[verse]
+'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r]
+	      [--root] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]
 
 DESCRIPTION
 -----------
@@ -62,7 +64,7 @@ separated with a single space are given.
 -s::
 	By default, "git-diff-tree --stdin" shows differences,
 	either in machine-readable form (without '-p') or in patch
-	form (with '-p').  This output can be supressed.  It is
+	form (with '-p').  This output can be suppressed.  It is
 	only useful with '-v' flag.
 
 -v::
@@ -74,6 +76,10 @@ separated with a single space are given.
 	commit message.  Without "=<style>", it defaults to
 	medium.
 
+--no-commit-id::
+	git-diff-tree outputs a line with the commit ID when
+	applicable.  This flag suppressed the commit ID output.
+
 
 Limiting Output
 ---------------

Documentation/git-diff.txt

@@ -17,14 +17,16 @@ ent and the index file, or the index file and the working tree.
 The combination of what is compared with what is determined by
 the number of ents given to the command.
 
-`----------------`--------`-----------------------------`------------------
+* When no <ent> is given, the working tree and the index
-Number of ents    Options  What's Compared               Underlying command
+  file is compared, using `git-diff-files`.
----------------------------------------------------------------------------
+
-0                 -        index file and working tree   git-diff-files
+* When one <ent> is given, the working tree and the named
-1                 --cached ent and index file            git-diff-index
+  tree is compared, using `git-diff-index`.  The option
-1                 -        ent and working tree          git-diff-index
+  `--cached` can be given to compare the index file and
-2                 -        two ents                      git-diff-tree
+  the named tree.
----------------------------------------------------------------------------
+
+* When two <ent>s are given, these two trees are compared
+  using `git-diff-tree`.
 
 OPTIONS
 -------
@@ -38,6 +40,68 @@ OPTIONS
 	commands.
 
 
+EXAMPLES
+--------
+
+Various ways to check your working tree::
++
+------------
+$ git diff <1>
+$ git diff --cached <2>
+$ git diff HEAD <3>
+
+<1> changes in the working tree since your last git-update-index.
+<2> changes between the index and your last commit; what you
+would be committing if you run "git commit" without "-a" option.
+<3> changes in the working tree since your last commit; what you
+would be committing if you run "git commit -a"
+------------
+
+Comparing with arbitrary commits::
++
+------------
+$ git diff test <1>
+$ git diff HEAD -- ./test <2>
+$ git diff HEAD^ HEAD <3>
+
+<1> instead of using the tip of the current branch, compare with the
+tip of "test" branch.
+<2> instead of comparing with the tip of "test" branch, compare with
+the tip of the current branch, but limit the comparison to the
+file "test".
+<3> compare the version before the last commit and the last commit.
+------------
+
+
+Limiting the diff output::
++
+------------
+$ git diff --diff-filter=MRC <1>
+$ git diff --name-status -r <2>
+$ git diff arch/i386 include/asm-i386 <3>
+
+<1> show only modification, rename and copy, but not addition
+nor deletion.
+<2> show only names and the nature of change, but not actual
+diff output.  --name-status disables usual patch generation
+which in turn also disables recursive behaviour, so without -r
+you would only see the directory name if there is a change in a
+file in a subdirectory.
+<3> limit diff output to named subtrees.
+------------
+
+Munging the diff output::
++
+------------
+$ git diff --find-copies-harder -B -C <1>
+$ git diff -R <2>
+
+<1> spend extra cycles to find renames, copies and complete
+rewrites (very expensive).
+<2> output diff in reverse.
+------------
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

Documentation/git-fetch-pack.txt

@@ -8,7 +8,7 @@ git-fetch-pack - Receive missing objects from another repository.
 
 SYNOPSIS
 --------
-git-fetch-pack [-q] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...]
+git-fetch-pack [-q] [-k] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...]
 
 DESCRIPTION
 -----------
@@ -29,6 +29,11 @@ OPTIONS
 	Pass '-q' flag to 'git-unpack-objects'; this makes the
 	cloning process less verbose.
 
+-k::
+	Do not invoke 'git-unpack-objects' on received data, but
+	create a single packfile out of it instead, and store it
+	in the object database.
+
 --exec=<git-upload-pack>::
 	Use this to specify the path to 'git-upload-pack' on the
 	remote side, if is not found on your $PATH.

Documentation/git-fetch.txt

@@ -8,7 +8,7 @@ git-fetch - Download objects and a head from another repository.
 
 SYNOPSIS
 --------
-'git-fetch' <repository> <refspec>...
+'git-fetch' <options> <repository> <refspec>...
 
 
 DESCRIPTION
@@ -17,24 +17,16 @@ Fetches named heads or tags from another repository, along with
 the objects necessary to complete them.
 
 The ref names and their object names of fetched refs are stored
-in $GIT_DIR/FETCH_HEAD.  This information is left for a later merge
+in `.git/FETCH_HEAD`.  This information is left for a later merge
-operation done by "git resolve" or "git octopus".
+operation done by "git merge".
 
 
 OPTIONS
 -------
+include::fetch-options.txt[]
+
 include::pull-fetch-param.txt[]
 
--a, \--append::
-	Append ref names and object names of fetched refs to the
-	existing contents of $GIT_DIR/FETCH_HEAD.  Without this
-	option old data in $GIT_DIR/FETCH_HEAD will be overwritten.
-
--u, \--update-head-ok::
-	By default 'git-fetch' refuses to update the head which
-	corresponds to the current branch.  This flag disables the
-	check.  Note that fetching into the current branch will not
-	update the index and working directory, so use it with care.
 
 
 SEE ALSO

Documentation/git-format-patch.txt

@@ -8,7 +8,9 @@ git-format-patch - Prepare patches for e-mail submission.
 
 SYNOPSIS
 --------
-'git-format-patch' [-n][-o <dir>|--stdout][-k][--mbox][--diff-options] <his> [<mine>]
+[verse]
+'git-format-patch' [-n | -k] [-o <dir> | --stdout] [-s] [-c] [--mbox]
+		 [--diff-options] <his> [<mine>]
 
 DESCRIPTION
 -----------
@@ -32,23 +34,34 @@ processing with applymbox.
 
 OPTIONS
 -------
--o <dir>::
+-o|--output-directory <dir>::
 	Use <dir> to store the resulting files, instead of the
 	current working directory.
 
--n::
+-n|--numbered::
 	Name output in '[PATCH n/m]' format.
 
--k::
+-k|--keep-subject::
 	Do not strip/add '[PATCH]' from the first line of the
 	commit log message.
 
---author, --date::
+-a|--author, -d|--date::
 	Output From: and Date: headers for commits made by
 	yourself as well.  Usually these are output only for
 	commits made by people other than yourself.
 
---mbox::
+-s|--signoff::
+	Add `Signed-off-by:` line to the commit message, using
+	the committer identity of yourself.
+
+-c|--check::
+        Display suspicious lines in the patch.  The definition
+        of 'suspicious lines' is currently the lines that has
+        trailing whitespaces, and the lines whose indentation
+        has a SP character immediately followed by a TAB
+        character.
+
+-m|--mbox::
 	Format the output files for closer to mbox format by
 	adding a phony Unix "From " line, so they can be
 	concatenated together and fed to `git-applymbox`.
@@ -73,10 +86,19 @@ git-format-patch origin::
 	pulled from origin the last time in a patch form for
 	e-mail submission.
 
+git-format-patch -M -B origin::
+	The same as the previous one, except detect and handle
+	renames and complete rewrites intelligently to produce
+	renaming patch.  A renaming patch reduces the amount of
+	text output, and generally makes it easier to review
+	it.  Note that the "patch" program does not understand
+	renaming patch well, so use it only when you know the
+	recipient uses git to apply your patch.
+
 
 See Also
 --------
-gitlink:git-am[1], gitlink:git-send-email
+gitlink:git-am[1], gitlink:git-send-email[1]
 
 
 Author

Documentation/git-fsck-objects.txt

@@ -8,7 +8,9 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the
 
 SYNOPSIS
 --------
-'git-fsck-objects' [--tags] [--root] [--unreachable] [--cache] [--standalone | --full] [--strict] [<object>*]
+[verse]
+'git-fsck-objects' [--tags] [--root] [--unreachable] [--cache]
+		 [--standalone | --full] [--strict] [<object>*]
 
 DESCRIPTION
 -----------
@@ -33,7 +35,7 @@ index file and all SHA1 references in .git/refs/* as heads.
 	Report tags.
 
 --cache::
-	Consider any object recorded in the cache also as a head node for
+	Consider any object recorded in the index also as a head node for
 	an unreachability trace.
 
 --standalone::
@@ -68,7 +70,7 @@ that aren't readable from any of the specified head nodes.
 
 So for example
 
-	git-fsck-objects --unreachable $(cat .git/HEAD .git/refs/heads/*)
+	git-fsck-objects --unreachable HEAD $(cat .git/refs/heads/*)
 
 will do quite a _lot_ of verification on the tree. There are a few
 extra validity tests to be added (make sure that tree objects are
@@ -125,7 +127,7 @@ GIT_OBJECT_DIRECTORY::
 	used to specify the object database root (usually $GIT_DIR/objects)
 
 GIT_INDEX_FILE::
-	used to specify the index file of the cache
+	used to specify the index file of the index
 
 GIT_ALTERNATE_OBJECT_DIRECTORIES::
 	used to specify additional object database roots (usually unset)

Documentation/git-grep.txt

@@ -8,7 +8,7 @@ git-grep - print lines matching a pattern
 
 SYNOPSIS
 --------
-'git-grep' <option>... <pattern> <path>...
+'git-grep' [<option>...] <pattern> [<path>...]
 
 DESCRIPTION
 -----------
@@ -27,7 +27,6 @@ OPTIONS
 	The pattern to look for.
 
 <path>...::
-
 	Optional paths to limit the set of files to be searched;
 	passed to `git-ls-files`.
 

Documentation/git-hash-object.txt

@@ -8,7 +8,7 @@ git-hash-object - Computes object ID and optionally creates a blob from a file.
 
 SYNOPSIS
 --------
-'git-hash-object' [-t <type>] [-w] <any-file-on-the-filesystem>
+'git-hash-object' [-t <type>] [-w] [--stdin] [--] <file>...
 
 DESCRIPTION
 -----------
@@ -16,7 +16,7 @@ Computes the object ID value for an object with specified type
 with the contents of the named file (which can be outside of the
 work tree), and optionally writes the resulting object into the
 object database.  Reports its object ID to its standard output.
-This is used by "git-cvsimport" to update the cache
+This is used by "git-cvsimport" to update the index
 without modifying files in the work tree.  When <type> is not
 specified, it defaults to "blob". 
 
@@ -29,6 +29,9 @@ OPTIONS
 -w::
 	Actually write the object into the object database.
 
+--stdin::
+	Read the object from standard input instead of from a file.
+
 Author
 ------
 Written by Junio C Hamano <junkio@cox.net>

Documentation/git-http-fetch.txt

@@ -3,17 +3,23 @@ git-http-fetch(1)
 
 NAME
 ----
-git-http-fetch - Downloads a remote git repository via HTTP
+git-http-fetch - downloads a remote git repository via HTTP
 
 
 SYNOPSIS
 --------
-'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url
+'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] <commit> <url>
 
 DESCRIPTION
 -----------
 Downloads a remote git repository via HTTP.
 
+OPTIONS
+-------
+commit-id::
+        Either the hash or the filename under [URL]/refs/ to
+        pull.
+
 -c::
 	Get the commit objects.
 -t::

Documentation/git-http-push.txt

@@ -0,0 +1,89 @@
+git-http-push(1)
+================
+
+NAME
+----
+git-http-push - Push missing objects using HTTP/DAV.
+
+
+SYNOPSIS
+--------
+'git-http-push' [--complete] [--force] [--verbose] <url> <ref> [<ref>...]
+
+DESCRIPTION
+-----------
+Sends missing objects to remote repository, and updates the
+remote branch.
+
+
+OPTIONS
+-------
+--complete::
+	Do not assume that the remote repository is complete in its
+	current state, and verify all objects in the entire local
+	ref's history exist in the remote repository.
+
+--force::
+	Usually, the command refuses to update a remote ref that
+	is not an ancestor of the local ref used to overwrite it.
+	This flag disables the check.  What this means is that
+	the remote repository can lose commits; use it with
+	care.
+
+--verbose::
+	Report the list of objects being walked locally and the
+	list of objects successfully sent to the remote repository.
+
+<ref>...:
+	The remote refs to update.
+
+
+Specifying the Refs
+-------------------
+
+A '<ref>' specification can be either a single pattern, or a pair
+of such patterns separated by a colon ":" (this means that a ref name
+cannot have a colon in it).  A single pattern '<name>' is just a 
+shorthand for '<name>:<name>'.
+
+Each pattern pair consists of the source side (before the colon)
+and the destination side (after the colon).  The ref to be
+pushed is determined by finding a match that matches the source
+side, and where it is pushed is determined by using the
+destination side.
+
+ - It is an error if <src> does not match exactly one of the
+   local refs.
+
+ - If <dst> does not match any remote ref, either
+
+   * it has to start with "refs/"; <dst> is used as the
+     destination literally in this case.
+
+   * <src> == <dst> and the ref that matched the <src> must not
+     exist in the set of remote refs; the ref matched <src>
+     locally is used as the name of the destination.
+
+Without '--force', the <src> ref is stored at the remote only if
+<dst> does not exist, or <dst> is a proper subset (i.e. an
+ancestor) of <src>.  This check, known as "fast forward check",
+is performed in order to avoid accidentally overwriting the
+remote ref and lose other peoples' commits from there.
+
+With '--force', the fast forward check is disabled for all refs.
+
+Optionally, a <ref> parameter can be prefixed with a plus '+' sign
+to disable the fast-forward check only on that ref.
+
+
+Author
+------
+Written by Nick Hengeveld <nickh@reactrix.com>
+
+Documentation
+--------------
+Documentation by Nick Hengeveld
+
+GIT
+---
+Part of the gitlink:git[7] suite

Documentation/git-init-db.txt

@@ -8,7 +8,17 @@ git-init-db - Creates an empty git repository
 
 SYNOPSIS
 --------
-'git-init-db'
+'git-init-db' [--template=<template_directory>] [--shared]
+
+
+OPTIONS
+-------
+--template=<template_directory>::
+	Provide the directory in from which templates will be used.
+
+--shared::
+	Specify that the git repository is to be shared amongst several users.
+
 
 DESCRIPTION
 -----------
@@ -16,14 +26,38 @@ This simply creates an empty git repository - basically a `.git` directory
 and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories,
 and links `.git/HEAD` symbolically to `.git/refs/heads/master`.
 
-If the 'GIT_DIR' environment variable is set then it specifies a path
+If the `$GIT_DIR` environment variable is set then it specifies a path
 to use instead of `./.git` for the base of the repository.
 
-If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY'
+If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY`
 environment variable then the sha1 directories are created underneath -
 otherwise the default `$GIT_DIR/objects` directory is used.
 
-"git-init-db" won't hurt an existing repository.
+A shared repository allows users belonging to the same group to push into that
+repository. When specifying `--shared` the config variable "core.sharedRepository" 
+is set to 'true' so that directories under `$GIT_DIR` are made group writable
+(and g+sx, since the git group may be not the primary group of all users).
+
+
+Running `git-init-db` in an existing repository is safe. It will not overwrite
+things that are already there. The primary reason for rerunning `git-init-db`
+is to pick up newly added templates.
+
+
+
+EXAMPLES
+--------
+
+Start a new git repository for an existing code base::
++
+----------------
+$ cd /path/to/my/codebase
+$ git-init-db <1>
+$ git-add . <2>
+
+<1> prepare /path/to/my/codebase/.git directory
+<2> add all existing file to the index
+----------------
 
 
 Author

Documentation/git-log.txt

@@ -20,7 +20,7 @@ This manual page describes only the most frequently used options.
 
 OPTIONS
 -------
---pretty=<format>:
+--pretty=<format>::
 	Controls the way the commit log is formatted.
 
 --max-count=<n>::

Documentation/git-lost-found.txt

@@ -0,0 +1,78 @@
+git-lost-found(1)
+=================
+
+NAME
+----
+git-lost-found - Recover lost refs that luckily have not yet been pruned.
+
+SYNOPSIS
+--------
+'git-lost-found'
+
+DESCRIPTION
+-----------
+Finds dangling commits and tags from the object database, and
+creates refs to them in .git/lost-found/ directory.  Commits and
+tags that dereference to commits go to .git/lost-found/commit
+and others are stored in .git/lost-found/other directory.
+
+
+OUTPUT
+------
+One line description from the commit and tag found along with
+their object name are printed on the standard output.
+
+
+EXAMPLE
+-------
+
+Suppose you run 'git tag -f' and mistyped the tag to overwrite.
+The ref to your tag is overwritten, but until you run 'git
+prune', it is still there.
+
+------------
+$ git lost-found
+[1ef2b196d909eed523d4f3c9bf54b78cdd6843c6] GIT 0.99.9c
+...
+------------
+
+Also you can use gitk to browse how they relate to each other
+and existing (probably old) tags.
+
+------------
+$ gitk $(cd .git/lost-found/commit && echo ??*)
+------------
+
+After making sure that it is the object you are looking for, you
+can reconnect it to your regular .git/refs hierarchy.
+
+------------
+$ git cat-file -t 1ef2b196
+tag
+$ git cat-file tag 1ef2b196
+object fa41bbce8e38c67a218415de6cfa510c7e50032a
+type commit
+tag v0.99.9c
+tagger Junio C Hamano <junkio@cox.net> 1131059594 -0800
+
+GIT 0.99.9c
+
+This contains the following changes from the "master" branch, since
+...
+$ git update-ref refs/tags/not-lost-anymore 1ef2b196
+$ git rev-parse not-lost-anymore
+1ef2b196d909eed523d4f3c9bf54b78cdd6843c6
+------------
+
+Author
+------
+Written by Junio C Hamano 濱野 純 <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite

Documentation/git-ls-files.txt

@@ -3,7 +3,7 @@ git-ls-files(1)
 
 NAME
 ----
-git-ls-files - Information about files in the cache/working directory
+git-ls-files - Information about files in the index/working directory
 
 
 SYNOPSIS
@@ -13,7 +13,8 @@ SYNOPSIS
 		(-[c|d|o|i|s|u|k|m])\*
 		[-x <pattern>|--exclude=<pattern>]
 		[-X <file>|--exclude-from=<file>]
-		[--exclude-per-directory=<file>] [--] [<file>]\*
+		[--exclude-per-directory=<file>] 
+		[--full-name] [--] [<file>]\*
 
 DESCRIPTION
 -----------
@@ -73,10 +74,16 @@ OPTIONS
 	H::	cached
 	M::	unmerged
 	R::	removed/deleted
-	C::	modifed/changed
+	C::	modified/changed
 	K::	to be killed
 	?	other
 
+--full-name::
+	When run from a subdirectory, the command usually
+	outputs paths relative to the current directory.  This
+	option forces paths to be output relative to the project
+	top directory.
+
 --::
 	Do not interpret any more arguments as options.
 

Documentation/git-ls-remote.txt

@@ -17,7 +17,7 @@ Displays the references other repository has.
 
 OPTIONS
 -------
---heads --tags::
+-h|--heads, -t|--tags::
 	Limit to only refs/heads and refs/tags, respectively.
 	These options are _not_ mutually exclusive; when given
 	both, references stored in refs/heads and refs/tags are

Documentation/git-ls-tree.txt

@@ -8,12 +8,15 @@ git-ls-tree - Lists the contents of a tree object.
 
 SYNOPSIS
 --------
-'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
+'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...]
 
 DESCRIPTION
 -----------
-Lists the contents of a tree object, like what "/bin/ls -a" does
+Lists the contents of a given tree object, like what "/bin/ls -a" does
-in the current working directory.
+in the current working directory. Note that the usage is subtly different,
+though - 'paths' denote just a list of patterns to match, e.g. so specifying
+directory name (without '-r') will behave differently, and order of the
+arguments does not matter.
 
 OPTIONS
 -------
@@ -21,36 +24,48 @@ OPTIONS
 	Id of a tree-ish.
 
 -d::
-	show only the named tree entry itself, not its children
+	Show only the named tree entry itself, not its children.
 
 -r::
-	recurse into sub-trees
+	Recurse into sub-trees.
+
+-t::
+	Show tree entries even when going to recurse them. Has no effect
+	if '-r' was not passed. '-d' implies '-t'.
 
 -z::
-	\0 line termination on output
+	\0 line termination on output.
+
+--name-only::
+--name-status::
+	List only filenames (instead of the "long" output), one per line.
 
 paths::
-	When paths are given, show them.  Otherwise implicitly
+	When paths are given, show them (note that this isn't really raw
-	uses the root level of the tree as the sole path argument.
+	pathnames, but rather a list of patterns to match).  Otherwise
+	implicitly uses the root level of the tree as the sole path argument.
 
 
 Output Format
 -------------
         <mode> SP <type> SP <object> TAB <file>
 
-When `-z` option is not used, TAB, LF, and backslash characters
+When the `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
+in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
-respectively.
 
 
 Author
 ------
-Written by Linus Torvalds <torvalds@osdl.org>
+Written by Petr Baudis <pasky@suse.cz>
-Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>
+Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>,
+another major rewrite by Linus Torvalds <torvalds@osdl.org>
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+Documentation by David Greaves, Junio C Hamano and the git-list
+<git@vger.kernel.org>.
+
+This manual page is a stub. You can help the git documentation by expanding it.
 
 GIT
 ---

Documentation/git-mailinfo.txt

@@ -8,7 +8,7 @@ git-mailinfo - Extracts patch from a single e-mail message.
 
 SYNOPSIS
 --------
-'git-mailinfo' [-k] [-u] <msg> <patch>
+'git-mailinfo' [-k] [-u | --encoding=<encoding>] <msg> <patch>
 
 
 DESCRIPTION
@@ -37,10 +37,17 @@ OPTIONS
 	author email are taken from the e-mail without any
 	charset conversion, after minimally decoding MIME
 	transfer encoding.  This flag causes the resulting
-	commit to be encoded in utf-8 by transliterating them.
+	commit to be encoded in the encoding specified by
+	i18n.commitencoding configuration (defaults to utf-8) by
+	transliterating them. 
 	Note that the patch is always used as is without charset
 	conversion, even with this flag.
 
+--encoding=<encoding>::
+	Similar to -u but if the local convention is different
+	from what is specified by i18n.commitencoding, this flag
+	can be used to override it.
+
 <msg>::
 	The commit log message extracted from e-mail, usually
 	except the title line which comes from e-mail Subject.

Documentation/git-mailsplit.txt

@@ -7,7 +7,7 @@ git-mailsplit - Totally braindamaged mbox splitter program.
 
 SYNOPSIS
 --------
-'git-mailsplit' [-d<prec>] [<mbox>] <directory>
+'git-mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>...]
 
 DESCRIPTION
 -----------
@@ -23,11 +23,18 @@ OPTIONS
 <directory>::
 	Directory in which to place the individual messages.
 
+-b::
+	If any file doesn't begin with a From line, assume it is a
+	single mail message instead of signalling error.
+
 -d<prec>::
 	Instead of the default 4 digits with leading zeros,
 	different precision can be specified for the generated
 	filenames.
 
+-f<nn>::
+	Skip the first <nn> numbers, for example if -f3 is specified,
+	start the numbering with 0004.
 
 Author
 ------

Documentation/git-merge-index.txt

@@ -12,7 +12,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This looks up the <file>(s) in the cache and, if there are any merge
+This looks up the <file>(s) in the index and, if there are any merge
 entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
 argument if no file), and <file> as argument 4.  File modes for the three
 files are passed as arguments 5, 6 and 7.
@@ -20,10 +20,10 @@ files are passed as arguments 5, 6 and 7.
 OPTIONS
 -------
 --::
-	Interpret all following arguments as filenames.
+	Do not interpret any more arguments as options.
 
 -a::
-	Run merge against all files in the cache that need merging.
+	Run merge against all files in the index that need merging.
 
 -o::
 	Instead of stopping at the first failed merge, do all of them

Documentation/git-merge.txt

@@ -19,7 +19,7 @@ which drives multiple merge strategy scripts.
 
 OPTIONS
 -------
-include::merge-pull-opts.txt[]
+include::merge-options.txt[]
 
 <msg>::
 	The commit message to be used for the merge commit (in case
@@ -34,6 +34,110 @@ include::merge-pull-opts.txt[]
 	least one <remote>.  Specifying more than one <remote>
 	obviously means you are trying an Octopus.
 
+include::merge-strategies.txt[]
+
+
+If you tried a merge which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
+HOW MERGE WORKS
+---------------
+
+A merge is always between the current `HEAD` and one or more
+remote branch heads, and the index file must exactly match the
+tree of `HEAD` commit (i.e. the contents of the last commit) when
+it happens.  In other words, `git-diff --cached HEAD` must
+report no changes.
+
+[NOTE]
+This is a bit of lie.  In certain special cases, your index are
+allowed to be different from the tree of `HEAD` commit.  The most
+notable case is when your `HEAD` commit is already ahead of what
+is being merged, in which case your index can have arbitrary
+difference from your `HEAD` commit.  Otherwise, your index entries
+are allowed have differences from your `HEAD` commit that match
+the result of trivial merge (e.g. you received the same patch
+from external source to produce the same result as what you are
+merging).  For example, if a path did not exist in the common
+ancestor and your head commit but exists in the tree you are
+merging into your repository, and if you already happen to have
+that path exactly in your index, the merge does not have to
+fail.
+
+Otherwise, merge will refuse to do any harm to your repository
+(that is, it may fetch the objects from remote, and it may even
+update the local branch used to keep track of the remote branch
+with `git pull remote rbranch:lbranch`, but your working tree,
+`.git/HEAD` pointer and index file are left intact).
+
+You may have local modifications in the working tree files.  In
+other words, `git-diff` is allowed to report changes.
+However, the merge uses your working tree as the working area,
+and in order to prevent the merge operation from losing such
+changes, it makes sure that they do not interfere with the
+merge. Those complex tables in read-tree documentation define
+what it means for a path to "interfere with the merge".  And if
+your local modifications interfere with the merge, again, it
+stops before touching anything.
+
+So in the above two "failed merge" case, you do not have to
+worry about lossage of data --- you simply were not ready to do
+a merge, so no merge happened at all.  You may want to finish
+whatever you were in the middle of doing, and retry the same
+pull after you are done and ready.
+
+When things cleanly merge, these things happen:
+
+1. the results are updated both in the index file and in your
+   working tree,
+2. index file is written out as a tree,
+3. the tree gets committed, and 
+4. the `HEAD` pointer gets advanced.
+
+Because of 2., we require that the original state of the index
+file to match exactly the current `HEAD` commit; otherwise we
+will write out your local changes already registered in your
+index file along with the merge result, which is not good.
+Because 1. involves only the paths different between your
+branch and the remote branch you are pulling from during the
+merge (which is typically a fraction of the whole tree), you can
+have local modifications in your working tree as long as they do
+not overlap with what the merge updates.
+
+When there are conflicts, these things happen:
+
+1. `HEAD` stays the same.
+
+2. Cleanly merged paths are updated both in the index file and
+   in your working tree.
+
+3. For conflicting paths, the index file records up to three
+   versions; stage1 stores the version from the common ancestor,
+   stage2 from `HEAD`, and stage3 from the remote branch (you
+   can inspect the stages with `git-ls-files -u`).  The working
+   tree files have the result of "merge" program; i.e. 3-way
+   merge result with familiar conflict markers `<<< === >>>`.
+
+4. No other changes are done.  In particular, the local
+   modifications you had before you started merge will stay the
+   same and the index entries for them stay as they were,
+   i.e. matching `HEAD`.
+
+After seeing a conflict, you can do two things:
+
+ * Decide not to merge.  The only clean-up you need are to reset
+   the index file to the `HEAD` commit to reverse 2. and to clean
+   up working tree changes made by 2. and 3.; `git-reset` can
+   be used for this.
+
+ * Resolve the conflicts.  `git-diff` would report only the
+   conflicting paths because of the above 2. and 3..  Edit the
+   working tree files into a desirable shape, `git-update-index`
+   them, to make the index file contain what the merge result
+   should be, and run `git-commit` to commit the result.
+
 
 SEE ALSO
 --------

Documentation/git-mv.txt

@@ -8,14 +8,17 @@ git-mv - Script used to move or rename a file, directory or symlink.
 
 SYNOPSIS
 --------
-'git-mv' [-f] [-n] <source> <destination>
+'git-mv' <options>... <args>...
-'git-mv' [-f] [-k] [-n] <source> ... <destination directory>
 
 DESCRIPTION
 -----------
 This script is used to move or rename a file, directory or symlink.
+
+ git-mv [-f] [-n] <source> <destination>
+ git-mv [-f] [-n] [-k] <source> ... <destination directory>
+
 In the first form, it renames <source>, which must exist and be either
-a file, symlink or directory, to <destination>, which must not exist.
+a file, symlink or directory, to <destination>.
 In the second form, the last argument has to be an existing
 directory; the given sources will be moved into this directory.
 
@@ -25,7 +28,7 @@ committed.
 OPTIONS
 -------
 -f::
-	Force renaming or moving even targets exist
+	Force renaming or moving of a file even if the target exists
 -k::
         Skip move or rename actions which would lead to an error
 	condition. An error happens when a source is neither existing nor

Documentation/git-octopus.txt

@@ -1,38 +0,0 @@
-git-octopus(1)
-==============
-
-NAME
-----
-git-octopus - Merge more than two commits.
-
-
-SYNOPSIS
---------
-'git-octopus'
-
-DESCRIPTION
------------
-After running 'git fetch', $GIT_DIR/FETCH_HEAD contains the
-following information, one line per remote ref:
-
-------------------------------------------------
-<object name>	<ref name> from <repository>
-------------------------------------------------
-
-Using this information, create and commit an Octopus merge on
-top of the current HEAD.
-
-
-Author
-------
-Written by Junio C Hamano <junkio@cox.net>
-
-
-Documentation
---------------
-Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
-
-GIT
----
-Part of the gitlink:git[7] suite
-

Documentation/git-pack-objects.txt

@@ -8,7 +8,7 @@ git-pack-objects - Create a packed archive of objects.
 
 SYNOPSIS
 --------
-'git-pack-objects' [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list
+'git-pack-objects' [--non-empty] [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list
 
 
 DESCRIPTION
@@ -46,7 +46,7 @@ base-name::
 	output of the command.
 
 --stdout::
-	Write the pack contents (what would have been writtin to
+	Write the pack contents (what would have been written to
 	.pack file) out to the standard output.
 
 --window and --depth::
@@ -70,6 +70,10 @@ base-name::
 	that are packed and not in the local object store
 	(i.e. borrowed from an alternate).
 
+--non-empty::
+        Only create a packed archive if it would contain at
+        least one object.
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

Documentation/git-pack-redundant.txt

@@ -0,0 +1,58 @@
+git-pack-redundant(1)
+=====================
+
+NAME
+----
+git-pack-redundant - Program used to find redundant pack files.
+
+
+SYNOPSIS
+--------
+'git-pack-redundant [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >'
+
+DESCRIPTION
+-----------
+This program computes which packs in your repository
+are redundant. The output is suitable for piping to
+'xargs rm' if you are in the root of the repository.
+
+git-pack-redundant accepts a list of objects on standard input. Any objects
+given will be ignored when checking which packs are required. This makes the 
+following command useful when wanting to remove packs which contain unreachable
+objects.
+
+git-fsck-objects --full --unreachable | cut -d ' ' -f3 | \
+git-pack-redundant --all | xargs rm
+
+OPTIONS
+-------
+
+
+--all::
+	Processes all packs. Any filenames on the commandline are ignored.
+
+--alt-odb::
+	Don't require objects present in packs from alternate object
+	directories to be present in local packs.
+
+--verbose::
+	Outputs some statistics to stderr. Has a small performance penalty.
+
+Author
+------
+Written by Lukas Sandström <lukass@etek.chalmers.se>
+
+Documentation
+--------------
+Documentation by Lukas Sandström <lukass@etek.chalmers.se>
+
+See-Also
+--------
+gitlink:git-pack-objects[1]
+gitlink:git-repack[1]
+gitlink:git-prune-packed[1]
+
+GIT
+---
+Part of the gitlink:git[7] suite
+

Documentation/git-prune-packed.txt

@@ -9,19 +9,28 @@ residing in a pack file.
 
 SYNOPSIS
 --------
-'git-prune-packed'
+'git-prune-packed' [-n]
+
 
 DESCRIPTION
 -----------
-This program search the GIT_OBJECT_DIR for all objects that currently exist in
+This program search the `$GIT_OBJECT_DIR` for all objects that currently
-a pack file as well as the independent object directories.
+exist in a pack file as well as the independent object directories.
 
 All such extra objects are removed.
 
 A pack is a collection of objects, individually compressed, with delta
 compression applied, stored in a single file, with an associated index file.
 
-Packs are used to reduce the load on mirror systems, backup engines, disk storage, etc.
+Packs are used to reduce the load on mirror systems, backup engines,
+disk storage, etc.
+
+
+OPTIONS
+-------
+-n::
+        Don't actually remove any objects, only show those that would have been
+        removed.
 
 Author
 ------

Documentation/git-prune.txt

@@ -8,15 +8,16 @@ git-prune - Prunes all unreachable objects from the object database
 
 SYNOPSIS
 --------
-'git-prune' [-n]
+'git-prune' [-n] [--] [<head>...]
 
 DESCRIPTION
 -----------
 
-This runs `git-fsck-objects --unreachable` using the heads
+This runs `git-fsck-objects --unreachable` using all the refs
-specified on the command line (or `$GIT_DIR/refs/heads/\*` and
+available in `$GIT_DIR/refs`, optionally with additional set of
-`$GIT_DIR/refs/tags/\*` if none is specified), and prunes all
+objects specified on the command line, and prunes all
-unreachable objects from the object database.  In addition, it
+objects unreachable from any of these head objects from the object database.
+In addition, it
 prunes the unpacked objects that are also found in packs by
 running `git prune-packed`.
 
@@ -27,6 +28,24 @@ OPTIONS
 	Do not remove anything; just report what it would
 	remove.
 
+--::
+	Do not interpret any more arguments as options.
+
+<head>...::
+	In addition to objects
+	reachable from any of our references, keep objects
+	reachable from listed <head>s.
+
+EXAMPLE
+-------
+
+To prune objects not used by your repository nor another that
+borrows from your repository via its
+`.git/objects/info/alternates`:
+
+------------
+$ git prune $(cd ../another && $(git-rev-parse --all))
+------------
 
 Author
 ------

Documentation/git-pull.txt

@@ -20,53 +20,16 @@ Note that you can use `.` (current directory) as the
 <repository> to pull from the local repository -- this is useful
 when merging local branches into the current branch.
 
+
 OPTIONS
 -------
+include::merge-options.txt[]
+
+include::fetch-options.txt[]
+
 include::pull-fetch-param.txt[]
 
--a, \--append::
+include::merge-strategies.txt[]
-	Append ref names and object names of fetched refs to the
-	existing contents of `$GIT_DIR/FETCH_HEAD`.  Without this
-	option old data in `$GIT_DIR/FETCH_HEAD` will be overwritten.
-
-include::merge-pull-opts.txt[]
-
-
-MERGE STRATEGIES
-----------------
-
-resolve::
-	This can only resolve two heads (i.e. the current branch
-	and another branch you pulled from) using 3-way merge
-	algorithm.  It tries to carefully detect criss-cross
-	merge ambiguities and is considered generally safe and
-	fast.  This is the default merge strategy when pulling
-	one branch.
-
-recursive::
-	This can only resolve two heads using 3-way merge
-	algorithm.  When there are more than one common
-	ancestors that can be used for 3-way merge, it creates a
-	merged tree of the common ancestores and uses that as
-	the reference tree for the 3-way merge.  This has been
-	reported to result in fewer merge conflicts without
-	causing mis-merges by tests done on actual merge commits
-	taken from Linux 2.6 kernel development history.
-	Additionally this can detect and handle merges involving
-	renames.
-
-octopus::
-	This resolves more than two-head case, but refuses to do
-	complex merge that needs manual resolution.  It is
-	primarily meant to be used for bundling topic branch
-	heads together.  This is the default merge strategy when
-	pulling more than one branch.
-
-ours::
-	This resolves any number of heads, but the result of the
-	merge is always the current branch head.  It is meant to
-	be used to supersede old development history of side
-	branches.
 
 
 EXAMPLES
@@ -106,7 +69,7 @@ $ git fetch origin master:origin +pu:pu maint:maint
 $ git pull . origin
 ------------------------------------------------
 +
-Here, a typical `$GIT_DIR/remotes/origin` file from a
+Here, a typical `.git/remotes/origin` file from a
 `git-clone` operation is used in combination with
 command line options to `git-fetch` to first update
 multiple branches of the local repository and then
@@ -119,7 +82,7 @@ known to have already obtained and made available
 all the necessary objects.
 
 
-Pull of multiple branches from one repository using `$GIT_DIR/remotes` file::
+Pull of multiple branches from one repository using `.git/remotes` file::
 +
 ------------------------------------------------
 $ cat .git/remotes/origin
@@ -132,7 +95,7 @@ $ git checkout master
 $ git pull origin
 ------------------------------------------------
 +
-Here, a typical `$GIT_DIR/remotes/origin` file from a
+Here, a typical `.git/remotes/origin` file from a
 `git-clone` operation has been hand-modified to include
 the branch-mapping of additional remote and local
 heads directly.  A single `git-pull` operation while
@@ -141,6 +104,11 @@ merge the remote `origin` head into the current,
 local `master` branch.
 
 
+If you tried a pull which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
 SEE ALSO
 --------
 gitlink:git-fetch[1], gitlink:git-merge[1]

Documentation/git-push.txt

@@ -16,6 +16,10 @@ DESCRIPTION
 Updates remote refs using local refs, while sending objects
 necessary to complete the given refs.
 
+You can make "interesting" things to happen on the repository
+every time you push into it, by setting up 'hooks' there.  See
+documentation for gitlink:git-receive-pack[1].
+
 
 OPTIONS
 -------
@@ -31,6 +35,7 @@ include::pull-fetch-param.txt[]
 	This flag disables the check.  What this means is that the
 	local repository can lose commits; use it with care.
 
+
 Author
 ------
 Written by Junio C Hamano <junkio@cox.net>

Documentation/git-read-tree.txt

@@ -3,32 +3,39 @@ git-read-tree(1)
 
 NAME
 ----
-git-read-tree - Reads tree information into the directory cache
+git-read-tree - Reads tree information into the index
 
 
 SYNOPSIS
 --------
-'git-read-tree' (<tree-ish> | [-m [-u|-i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
+'git-read-tree' (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
 
 
 DESCRIPTION
 -----------
-Reads the tree information given by <tree-ish> into the directory cache,
+Reads the tree information given by <tree-ish> into the index,
 but does not actually *update* any of the files it "caches". (see:
-git-checkout-index)
+gitlink:git-checkout-index[1])
 
-Optionally, it can merge a tree into the cache, perform a
+Optionally, it can merge a tree into the index, perform a
-fast-forward (i.e. 2-way) merge, or a 3-way merge, with the -m
+fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m`
-flag.  When used with -m, the -u flag causes it to also update
+flag.  When used with `-m`, the `-u` flag causes it to also update
 the files in the work tree with the result of the merge.
 
-Trivial merges are done by "git-read-tree" itself.  Only conflicting paths
+Trivial merges are done by `git-read-tree` itself.  Only conflicting paths
-will be in unmerged state when "git-read-tree" returns.
+will be in unmerged state when `git-read-tree` returns.
 
 OPTIONS
 -------
 -m::
-	Perform a merge, not just a read.
+	Perform a merge, not just a read.  The command will
+	refuse to run if your index file has unmerged entries,
+	indicating that you have not finished previous merge you
+	started.
+
+--reset::
+        Same as -m, except that unmerged entries are discarded
+        instead of failing.
 
 -u::
 	After a successful merge, update the files in the work
@@ -43,14 +50,13 @@ OPTIONS
 	trees that are not directly related to the current
 	working tree status into a temporary index file.
 
-
 <tree-ish#>::
 	The id of the tree object(s) to be read/merged.
 
 
 Merging
 -------
-If '-m' is specified, "git-read-tree" can perform 3 kinds of
+If `-m` is specified, `git-read-tree` can perform 3 kinds of
 merge, a single tree merge if only 1 tree is given, a
 fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
 provided.
@@ -59,23 +65,23 @@ provided.
 Single Tree Merge
 ~~~~~~~~~~~~~~~~~
 If only 1 tree is specified, git-read-tree operates as if the user did not
-specify '-m', except that if the original cache has an entry for a
+specify `-m`, except that if the original index has an entry for a
 given pathname, and the contents of the path matches with the tree
-being read, the stat info from the cache is used. (In other words, the
+being read, the stat info from the index is used. (In other words, the
-cache's stat()s take precedence over the merged tree's).
+index's stat()s take precedence over the merged tree's).
 
-That means that if you do a "git-read-tree -m <newtree>" followed by a
+That means that if you do a `git-read-tree -m <newtree>` followed by a
-"git-checkout-index -f -u -a", the "git-checkout-index" only checks out
+`git-checkout-index -f -u -a`, the `git-checkout-index` only checks out
 the stuff that really changed.
 
-This is used to avoid unnecessary false hits when "git-diff-files" is
+This is used to avoid unnecessary false hits when `git-diff-files` is
-run after git-read-tree.
+run after `git-read-tree`.
 
 
 Two Tree Merge
 ~~~~~~~~~~~~~~
 
-Typically, this is invoked as "git-read-tree -m $H $M", where $H
+Typically, this is invoked as `git-read-tree -m $H $M`, where $H
 is the head commit of the current repository, and $M is the head
 of a foreign tree, which is simply ahead of $H (i.e. we are in a
 fast forward situation).
@@ -88,7 +94,7 @@ the following:
 
      2. The user wants to fast-forward to $M.
 
-In this case, the "git-read-tree -m $H $M" command makes sure
+In this case, the `git-read-tree -m $H $M` command makes sure
 that no local change is lost as the result of this "merge".
 Here are the "carry forward" rules:
 
@@ -96,7 +102,7 @@ Here are the "carry forward" rules:
        -------------------------------------------------------
       0 nothing             nothing  nothing  (does not happen)
       1 nothing             nothing  exists   use M
-      2 nothing             exists   nothing  remove path from cache
+      2 nothing             exists   nothing  remove path from index
       3 nothing             exists   exists   use M
 
         clean I==H  I==M
@@ -109,7 +115,7 @@ Here are the "carry forward" rules:
       8 yes   N/A   no      nothing  exists   fail
       9 no    N/A   no      nothing  exists   fail
 
-     10 yes   yes   N/A     exists   nothing  remove path from cache
+     10 yes   yes   N/A     exists   nothing  remove path from index
      11 no    yes   N/A     exists   nothing  fail
      12 yes   no    N/A     exists   nothing  fail
      13 no    no    N/A     exists   nothing  fail
@@ -128,20 +134,20 @@ Here are the "carry forward" rules:
      20 yes   yes   no      exists   exists   use M
      21 no    yes   no      exists   exists   fail
 
-In all "keep index" cases, the cache entry stays as in the
+In all "keep index" cases, the index entry stays as in the
 original index file.  If the entry were not up to date,
 git-read-tree keeps the copy in the work tree intact when
 operating under the -u flag.
 
 When this form of git-read-tree returns successfully, you can
 see what "local changes" you made are carried forward by running
-"git-diff-index --cached $M".  Note that this does not
+`git-diff-index --cached $M`.  Note that this does not
-necessarily match "git-diff-index --cached $H" would have
+necessarily match `git-diff-index --cached $H` would have
 produced before such a two tree merge.  This is because of cases
 18 and 19 --- if you already had the changes in $M (e.g. maybe
-you picked it up via e-mail in a patch form), "git-diff-index
+you picked it up via e-mail in a patch form), `git-diff-index
---cached $H" would have told you about the change before this
+--cached $H` would have told you about the change before this
-merge, but it would not show in "git-diff-index --cached $M"
+merge, but it would not show in `git-diff-index --cached $M`
 output after two-tree merge.
 
 
@@ -150,31 +156,39 @@ output after two-tree merge.
 Each "index" entry has two bits worth of "stage" state. stage 0 is the
 normal one, and is the only one you'd see in any kind of normal use.
 
-However, when you do "git-read-tree" with three trees, the "stage"
+However, when you do `git-read-tree` with three trees, the "stage"
 starts out at 1.
 
 This means that you can do
 
-	git-read-tree -m <tree1> <tree2> <tree3>
+----------------
+$ git-read-tree -m <tree1> <tree2> <tree3>
+----------------
 
 and you will end up with an index with all of the <tree1> entries in
 "stage1", all of the <tree2> entries in "stage2" and all of the
-<tree3> entries in "stage3".
+<tree3> entries in "stage3".  When performing a merge of another
+branch into the current branch, we use the common ancestor tree
+as <tree1>, the current branch head as <tree2>, and the other
+branch head as <tree3>.
 
-Furthermore, "git-read-tree" has special-case logic that says: if you see
+Furthermore, `git-read-tree` has special-case logic that says: if you see
 a file that matches in all respects in the following states, it
 "collapses" back to "stage0":
 
    - stage 2 and 3 are the same; take one or the other (it makes no
-     difference - the same work has been done on stage 2 and 3)
+     difference - the same work has been done on our branch in
+     stage 2 and their branch in stage 3)
 
    - stage 1 and stage 2 are the same and stage 3 is different; take
-     stage 3 (some work has been done on stage 3)
+     stage 3 (our branch in stage 2 did not do anything since the
+     ancestor in stage 1 while their branch in stage 3 worked on
+     it)
 
    - stage 1 and stage 3 are the same and stage 2 is different take
-     stage 2 (some work has been done on stage 2)
+     stage 2 (we did something while they did nothing)
 
-The "git-write-tree" command refuses to write a nonsensical tree, and it
+The `git-write-tree` command refuses to write a nonsensical tree, and it
 will complain about unmerged entries if it sees a single entry that is not
 stage 0.
 
@@ -214,12 +228,10 @@ populated.  Here is an outline of how the algorithm works:
     matching "stage1" entry if it exists too.  .. all the normal
     trivial rules ..
 
-You would normally use "git-merge-index" with supplied
+You would normally use `git-merge-index` with supplied
-"git-merge-one-file" to do this last step.  The script
+`git-merge-one-file` to do this last step.  The script updates
-does not touch the files in the work tree, and the entire merge
+the files in the working tree as it merges each path and at the
-happens in the index file.  In other words, there is no need to
+end of a successful merge.
-worry about what is in the working directory, since it is never
-shown and never used.
 
 When you start a 3-way merge with an index file that is already
 populated, it is assumed that it represents the state of the
@@ -230,33 +242,54 @@ merge refuses to run if it finds an entry in the original index
 file that does not match stage 2.
 
 This is done to prevent you from losing your work-in-progress
-changes.  To illustrate, suppose you start from what has been
+changes, and mixing your random changes in an unrelated merge
+commit.  To illustrate, suppose you start from what has been
 commited last to your repository:
 
-    $ JC=`cat .git/HEAD`
+----------------
-    $ git-checkout-index -f -u -a $JC
+$ JC=`git-rev-parse --verify "HEAD^0"`
+$ git-checkout-index -f -u -a $JC
+----------------
 
 You do random edits, without running git-update-index.  And then
 you notice that the tip of your "upstream" tree has advanced
 since you pulled from him:
 
-    $ git-fetch rsync://.... linus
+----------------
-    $ LT=`cat .git/MERGE_HEAD`
+$ git-fetch git://.... linus
+$ LT=`cat .git/FETCH_HEAD`
+----------------
 
 Your work tree is still based on your HEAD ($JC), but you have
 some edits since.  Three-way merge makes sure that you have not
-added or modified cache entries since $JC, and if you haven't,
+added or modified index entries since $JC, and if you haven't,
 then does the right thing.  So with the following sequence:
 
-    $ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT
+----------------
-    $ git-merge-index git-merge-one-file -a
+$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT
-    $ echo "Merge with Linus" | \
+$ git-merge-index git-merge-one-file -a
-      git-commit-tree `git-write-tree` -p $JC -p $LT
+$ echo "Merge with Linus" | \
+  git-commit-tree `git-write-tree` -p $JC -p $LT
+----------------
 
-what you would commit is a pure merge between $JC and LT without
+what you would commit is a pure merge between $JC and $LT without
 your work-in-progress changes, and your work tree would be
 updated to the result of the merge.
 
+However, if you have local changes in the working tree that
+would be overwritten by this merge,`git-read-tree` will refuse
+to run to prevent your changes from being lost.
+
+In other words, there is no need to worry about what exists only
+in the working tree.  When you have local changes in a part of
+the project that is not involved in the merge, your changes do
+not interfere with the merge, and are kept intact.  When they
+*do* interfere, the merge does not even start (`git-read-tree`
+complains loudly and fails without modifying anything).  In such
+a case, you can simply continue doing what you were in the
+middle of doing, and when your working tree is ready (i.e. you
+have finished your work-in-progress), attempt the merge again.
+
 
 See Also
 --------

Documentation/git-receive-pack.txt

@@ -71,6 +71,10 @@ packed and is served via a dumb transport.
 	#!/bin/sh
 	exec git-update-server-info
 
+There are other real-world examples of using update and
+post-update hooks found in the Documentation/howto directory.
+
+
 OPTIONS
 -------
 <directory>::

Documentation/git-rename.txt

@@ -1,32 +0,0 @@
-git-rename(1)
-=============
-
-NAME
-----
-git-rename - Script used to rename a file, directory or symlink.
-
-
-SYNOPSIS
---------
-'git-rename' <source> <destination>
-
-DESCRIPTION
------------
-This script is used to rename a file, directory or symlink.
-
-The index is updated after successful completion, but the change must still be
-committed.
-
-Author
-------
-Written by Linus Torvalds <torvalds@osdl.org>
-Rewritten by Ryan Anderson <ryan@michonline.com>
-
-Documentation
---------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
-
-GIT
----
-Part of the gitlink:git[7] suite
-

Documentation/git-repack.txt

@@ -9,7 +9,7 @@ objects into pack files.
 
 SYNOPSIS
 --------
-'git-repack' [-a] [-d]
+'git-repack' [-a] [-d] [-l] [-n]
 
 DESCRIPTION
 -----------
@@ -39,6 +39,13 @@ OPTIONS
 	After packing, if the newly created packs make some
 	existing packs redundant, remove the redundant packs.
 
+-l::
+        Pass the `--local` option to `git pack-objects`, see
+        gitlink:git-pack-objects[1].
+
+-n::
+        Do not update the server information with
+        `git update-server-info`.
 
 Author
 ------

Documentation/git-repo-config.txt

@@ -0,0 +1,170 @@
+git-repo-config(1)
+==================
+
+NAME
+----
+git-repo-config - Get and set options in .git/config.
+
+
+SYNOPSIS
+--------
+'git-repo-config' name [value [value_regex]]
+'git-repo-config' --replace-all name [value [value_regex]]
+'git-repo-config' --get name [value_regex]
+'git-repo-config' --get-all name [value_regex]
+'git-repo-config' --unset name [value_regex]
+'git-repo-config' --unset-all name [value_regex]
+
+DESCRIPTION
+-----------
+You can query/set/replace/unset options with this command. The name is
+actually the section and the key separated by a dot, and the value will be
+escaped.
+
+If you want to set/unset an option which can occur on multiple lines, you
+should provide a POSIX regex for the value. If you want to handle the lines
+*not* matching the regex, just prepend a single exclamation mark in front
+(see EXAMPLES).
+
+This command will fail if
+
+. .git/config is invalid,
+. .git/config can not be written to,
+. no section was provided,
+. the section or key is invalid,
+. you try to unset an option which does not exist, or
+. you try to unset/set an option for which multiple lines match.
+
+
+OPTIONS
+-------
+
+--replace-all::
+	Default behaviour is to replace at most one line. This replaces
+	all lines matching the key (and optionally the value_regex)
+
+--get::
+	Get the value for a given key (optionally filtered by a regex
+	matching the value).
+
+--get-all::
+	Like get, but does not fail if the number of values for the key
+	is not exactly one.
+
+--unset::
+	Remove the line matching the key from .git/config.
+
+--unset-all::
+	Remove all matching lines from .git/config.
+
+
+EXAMPLE
+-------
+
+Given a .git/config like this:
+
+	#
+	# This is the config file, and
+	# a '#' or ';' character indicates
+	# a comment
+	#
+
+	; core variables
+	[core]
+		; Don't trust file modes
+		filemode = false
+
+	; Our diff algorithm
+	[diff]
+		external = "/usr/local/bin/gnu-diff -u"
+		renames = true
+
+	; Proxy settings
+	[proxy]
+		command="ssh" for "ssh://kernel.org/"
+		command="proxy-command" for kernel.org
+		command="myprotocol-command" for "my://"
+		command=default-proxy ; for all the rest
+
+you can set the filemode to true with
+
+------------
+% git repo-config core.filemode true
+------------
+
+The hypothetic proxy command entries actually have a postfix to discern
+to what URL they apply. Here is how to change the entry for kernel.org
+to "ssh".
+
+------------
+% git repo-config proxy.command '"ssh" for kernel.org' 'for kernel.org$'
+------------
+
+This makes sure that only the key/value pair for kernel.org is replaced.
+
+To delete the entry for renames, do
+
+------------
+% git repo-config --unset diff.renames
+------------
+
+If you want to delete an entry for a multivar (like proxy.command above),
+you have to provide a regex matching the value of exactly one line.
+
+To query the value for a given key, do
+
+------------
+% git repo-config --get core.filemode
+------------
+
+or
+
+------------
+% git repo-config core.filemode
+------------
+
+or, to query a multivar:
+
+------------
+% git repo-config --get proxy.command "for kernel.org$"
+------------
+
+If you want to know all the values for a multivar, do:
+
+------------
+% git repo-config --get-all proxy.command
+------------
+
+If you like to live dangerous, you can replace *all* proxy.commands by a
+new one with
+
+------------
+% git repo-config --replace-all proxy.command ssh
+------------
+
+However, if you really only want to replace the line for the default proxy,
+i.e. the one without a "for ..." postfix, do something like this:
+
+------------
+% git repo-config proxy.command ssh '! for '
+------------
+
+To actually match only values with an exclamation mark, you have to
+
+------------
+% git repo-config section.key value '[!]'
+------------
+
+
+Author
+------
+Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
+
+Documentation
+--------------
+Documentation by Johannes Schindelin.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+

Documentation/git-reset.txt

@@ -14,23 +14,137 @@ DESCRIPTION
 Sets the current head to the specified commit and optionally resets the
 index and working tree to match.
 
+This command is useful if you notice some small error in a recent
+commit (or set of commits) and want to redo that part without showing
+the undo in the history.
+
+If you want to undo a commit other than the latest on a branch,
+gitlink:git-revert[1] is your friend.
+
 OPTIONS
 -------
 --mixed::
-	Like --soft but reports what has not been updated. This is the
+	Resets the index but not the working tree (ie, the changed files
-	default action.
+	are preserved but not marked for commit) and reports what has not
+	been updated. This is the default action.
 
 --soft::
 	Does not touch the index file nor the working tree at all, but
-	requires them in a good order.
+	requires them to be in a good order. This leaves all your changed
+	files "Updated but not checked in", as gitlink:git-status[1] would
+	put it.
 
 --hard::
 	Matches the working tree and index to that of the tree being
-	switched to.
+	switched to. Any changes to tracked files in the working tree
+	since <commit-ish> are lost.
 
 <commit-ish>::
 	Commit to make the current HEAD.
 
+Examples
+~~~~~~~~
+
+Undo a commit and redo::
++
+------------
+$ git commit ...
+$ git reset --soft HEAD^ <1>
+$ edit <2>
+$ git commit -a -c ORIG_HEAD <3>
+
+<1> This is most often done when you remembered what you
+just committed is incomplete, or you misspelled your commit
+message, or both.  Leaves working tree as it was before "reset".
+<2> make corrections to working tree files.
+<3> "reset" copies the old head to .git/ORIG_HEAD; redo the
+commit by starting with its log message.  If you do not need to
+edit the message further, you can give -C option instead.
+------------
+
+Undo commits permanently::
++
+------------
+$ git commit ...
+$ git reset --hard HEAD~3 <1>
+
+<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad
+and you do not want to ever see them again.  Do *not* do this if
+you have already given these commits to somebody else.
+------------
+
+Undo a commit, making it a topic branch::
++
+------------
+$ git branch topic/wip <1>
+$ git reset --hard HEAD~3 <2>
+$ git checkout topic/wip <3>
+
+<1> You have made some commits, but realize they were premature
+to be in the "master" branch.  You want to continue polishing
+them in a topic branch, so create "topic/wip" branch off of the
+current HEAD.
+<2> Rewind the master branch to get rid of those three commits.
+<3> Switch to "topic/wip" branch and keep working.
+------------
+
+Undo update-index::
++
+------------
+$ edit <1>
+$ git-update-index frotz.c filfre.c
+$ mailx <2>
+$ git reset <3>
+$ git pull git://info.example.com/ nitfol <4>
+
+<1> you are happily working on something, and find the changes
+in these files are in good order.  You do not want to see them
+when you run "git diff", because you plan to work on other files
+and changes with these files are distracting.
+<2> somebody asks you to pull, and the changes sounds worthy of merging.
+<3> however, you already dirtied the index (i.e. your index does
+not match the HEAD commit).  But you know the pull you are going
+to make does not affect frotz.c nor filfre.c, so you revert the
+index changes for these two files.  Your changes in working tree
+remain there.
+<4> then you can pull and merge, leaving frotz.c and filfre.c
+changes still in the working tree.
+------------
+
+Undo a merge or pull::
++
+------------
+$ git pull <1>
+Trying really trivial in-index merge...
+fatal: Merge requires file-level merging
+Nope.
+...
+Auto-merging nitfol
+CONFLICT (content): Merge conflict in nitfol
+Automatic merge failed/prevented; fix up by hand
+$ git reset --hard <2>
+
+<1> try to update from the upstream resulted in a lot of
+conflicts; you were not ready to spend a lot of time merging
+right now, so you decide to do that later.
+<2> "pull" has not made merge commit, so "git reset --hard"
+which is a synonym for "git reset --hard HEAD" clears the mess
+from the index file and the working tree.
+
+$ git pull . topic/branch <3>
+Updating from 41223... to 13134...
+Fast forward
+$ git reset --hard ORIG_HEAD <4>
+
+<3> merge a topic branch into the current branch, which resulted
+in a fast forward.
+<4> but you decided that the topic branch is not ready for public
+consumption yet.  "pull" or "merge" always leaves the original
+tip of the current branch in ORIG_HEAD, so resetting hard to it
+brings your index file and the working tree back to that state,
+and resets the tip of the branch to that commit.
+------------
+
 Author
 ------
 Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org>

Documentation/git-rev-list.txt

@@ -8,18 +8,19 @@ git-rev-list - Lists commit objects in reverse chronological order
 
 SYNOPSIS
 --------
+[verse]
 'git-rev-list' [ \--max-count=number ]
-	[ \--max-age=timestamp ]
+	     [ \--max-age=timestamp ]
-	[ \--min-age=timestamp ]
+	     [ \--min-age=timestamp ]
-	[ \--sparse ]
+	     [ \--sparse ]
-	[ \--no-merges ]
+	     [ \--no-merges ]
-	[ \--all ]
+	     [ \--all ]
-	[ [ \--merge-order [ \--show-breaks ] ] | [ \--topo-order ] | ]
+	     [ [ \--merge-order [ \--show-breaks ] ] | [ \--topo-order ] ]
-	[ \--parents ]
+	     [ \--parents ]
-	[ \--objects [ \--unpacked ] ]
+	     [ \--objects [ \--unpacked ] ]
-	[ \--pretty | \--header | ]
+	     [ \--pretty | \--header ]
-	[ \--bisect ]
+	     [ \--bisect ]
-	<commit>... [ \-- <paths>... ]
+	     <commit>... [ \-- <paths>... ]
 
 DESCRIPTION
 -----------
@@ -129,7 +130,7 @@ the marked commit in the list.
 +
 Commits marked with (^) are not parents of the immediately preceding commit.
 These "breaks" represent necessary discontinuities implied by trying to
-represent an arbtirary DAG in a linear form.
+represent an arbitrary DAG in a linear form.
 +
 `--show-breaks` is only valid if `--merge-order` is also specified.
 

Documentation/git-revert.txt

@@ -7,7 +7,7 @@ git-revert - Revert an existing commit.
 
 SYNOPSIS
 --------
-'git-revert' [-n] <commit>
+'git-revert' [--edit | --no-edit] [-n] <commit>
 
 DESCRIPTION
 -----------
@@ -20,7 +20,16 @@ OPTIONS
 <commit>::
 	Commit to revert.
 
--n::
+-e|--edit::
+	With this option, `git-revert` will let you edit the commit
+	message prior committing the revert. This is the default if
+	you run the command from a terminal.
+
+--no-edit::
+	With this option, `git-revert` will not start the commit
+	message editor.
+
+-n|--no-commit::
 	Usually the command automatically creates a commit with
 	a commit log message stating which commit was reverted.
 	This flag applies the change necessary to revert the

Documentation/git-show-branch.txt

@@ -7,23 +7,40 @@ git-show-branch - Show branches and their commits.
 
 SYNOPSIS
 --------
-'git-show-branch [--all] [--heads] [--tags] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] <reference>...'
+'git-show-branch [--all] [--heads] [--tags] [--topo-order] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [<rev> | <glob>]...'
 
 DESCRIPTION
 -----------
-Shows the head commits from the named <reference> (or all refs under
+
-$GIT_DIR/refs/heads), and displays concise list of commit logs
+Shows the commit ancestry graph starting from the commits named
-to show their relationship semi-visually.
+with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads
+and/or $GIT_DIR/refs/tags) semi-visually.
+
+It cannot show more than 29 branches and commits at a time.
+
 
 OPTIONS
 -------
-<reference>::
+<rev>::
-	Name of the reference under $GIT_DIR/refs/.
+	Arbitrary extended SHA1 expression (see `git-rev-parse`)
+	that typically names a branch HEAD or a tag.
+
+<glob>::
+	A glob pattern that matches branch or tag names under
+	$GIT_DIR/refs.  For example, if you have many topic
+	branches under $GIT_DIR/refs/heads/topic, giving
+	`topic/*` would show all of them.
 
 --all --heads --tags::
 	Show all refs under $GIT_DIR/refs, $GIT_DIR/refs/heads,
 	and $GIT_DIR/refs/tags, respectively.
 
+--topo-order::
+        By default, the branches and their commits are shown in
+        reverse chronological order.  This option makes them
+        appear in topological order (i.e., descendant commits
+        are shown before their parents).
+
 --more=<n>::
 	Usually the command stops output upon showing the commit
 	that is the common ancestor of all the branches.  This
@@ -68,7 +85,7 @@ Following these N lines, one-line log for each commit is
 displayed, indented N places.  If a commit is on the I-th
 branch, the I-th indentation character shows a '+' sign;
 otherwise it shows a space.  Each commit shows a short name that
-can be used as an exended SHA1 to name that commit.
+can be used as an extended SHA1 to name that commit.
 
 The following example shows three branches, "master", "fixes"
 and "mhf":

Documentation/git-svnimport.txt

@@ -10,8 +10,8 @@ git-svnimport - Import a SVN repository into git
 SYNOPSIS
 --------
 'git-svnimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] [ -d | -D ]
-			[ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_nr_changes]
+			[ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev]
-			[ -b branch_subdir ] [ -t trunk_subdir ] [ -T tag_subdir ]
+			[ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ]
 			[ -s start_chg ] [ -m ] [ -M regex ]
 			<SVN_repository_URL> [ <path> ]
 
@@ -40,17 +40,17 @@ OPTIONS
 -s <start_rev>::
         Start importing at this SVN change number. The  default is 1.
 +
-When importing incementally, you might need to edit the .git/svn2git file.
+When importing incrementally, you might need to edit the .git/svn2git file.
 
 -i::
 	Import-only: don't perform a checkout after importing.  This option
-	ensures the working directory and cache remain untouched and will
+	ensures the working directory and index remain untouched and will
 	not create them if they do not exist.
 
--t <trunk_subdir>::
+-T <trunk_subdir>::
 	Name the SVN trunk. Default "trunk".
 
--T <tag_subdir>::
+-t <tag_subdir>::
 	Name the SVN subdirectory for tags. Default "tags".
 
 -b <branch_subdir>::
@@ -71,14 +71,11 @@ When importing incementally, you might need to edit the .git/svn2git file.
 	regex. It can be used with -m to also see the default regexes.
 	You must escape forward slashes.
 
--l <max_num_changes>::
+-l <max_rev>::
-	Limit the number of SVN changesets we pull before quitting.
+	Specify a maximum revision number to pull.
-	This option is necessary because the SVN library has serious memory
-	leaks; the recommended value for nontrivial imports is 100.
 
-	git-svnimport will still exit with a zero exit code. You can check
+	Formerly, this option controlled how many revisions to pull, due to
-	the size of the file ".git/svn2git" to determine whether to call
+	SVN memory leaks. (These have been worked around.)
-	the importer again.
 
 -v::
 	Verbosity: let 'svnimport' report what it is doing.

Documentation/git-symbolic-ref.txt

@@ -24,8 +24,8 @@ Traditionally, `.git/HEAD` is a symlink pointing at
 we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want
 to find out which branch we are on, we did `readlink .git/HEAD`.
 This was fine, and internally that is what still happens by
-default, but on platforms that does not have working symlinks,
+default, but on platforms that do not have working symlinks,
-or that does not have the `readlink(1)` command, this was a bit
+or that do not have the `readlink(1)` command, this was a bit
 cumbersome.  On some platforms, `ln -sf` does not even work as
 advertised (horrors).
 

Documentation/git-tag.txt

@@ -8,7 +8,7 @@ git-tag -  Create a tag object signed with GPG
 
 SYNOPSIS
 --------
-'git-tag' [-a | -s | -u <key-id>] [-f] [-m <msg>] <name> [<head>]
+'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>]
 
 DESCRIPTION
 -----------
@@ -23,13 +23,35 @@ creates a 'tag' object, and requires the tag message.  Unless
 in the tag message.
 
 Otherwise just the SHA1 object name of the commit object is
-written (i.e. an lightweight tag).
+written (i.e. a lightweight tag).
 
 A GnuPG signed tag object will be created when `-s` or `-u
 <key-id>` is used.  When `-u <key-id>` is not used, the
 committer identity for the current user is used to find the
 GnuPG key for signing.
 
+`-d <tag>` deletes the tag.
+
+OPTIONS
+-------
+-a::
+	Make an unsigned, annotated tag object
+
+-s::
+	Make a GPG-signed tag, using the default e-mail address's key
+
+-u <key-id>::
+	Make a GPG-signed tag, using the given key
+
+-f::
+	Replace an existing tag with the given name (instead of failing)
+
+-d::
+	Delete an existing tag with the given name
+
+-m <msg>::
+	Use the given tag message (instead of prompting)
+
 
 Author
 ------

Documentation/git-unpack-objects.txt

@@ -8,7 +8,7 @@ git-unpack-objects - Unpack objects from a packed archive.
 
 SYNOPSIS
 --------
-'git-unpack-objects' [-q] <pack-file
+'git-unpack-objects' [-n] [-q] <pack-file
 
 
 DESCRIPTION
@@ -19,6 +19,10 @@ one-object" format in $GIT_OBJECT_DIRECTORY.
 
 OPTIONS
 -------
+-n::
+        Only list the objects that would be unpacked, don't actually unpack
+        them.
+
 -q::
 	The command usually shows percentage progress.  This
 	flag suppresses it.

Documentation/git-update-index.txt

@@ -21,7 +21,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Modifies the index or directory cache. Each file mentioned is updated
-into the cache and any 'unmerged' or 'needs updating' state is
+into the index and any 'unmerged' or 'needs updating' state is
 cleared.
 
 The way "git-update-index" handles files it is told about can be modified
@@ -30,26 +30,26 @@ using the various options:
 OPTIONS
 -------
 --add::
-	If a specified file isn't in the cache already then it's
+	If a specified file isn't in the index already then it's
 	added.
 	Default behaviour is to ignore new files.
 
 --remove::
-	If a specified file is in the cache but is missing then it's
+	If a specified file is in the index but is missing then it's
 	removed.
 	Default behaviour is to ignore removed file.
 
 --refresh::
-	Looks at the current cache and checks to see if merges or
+	Looks at the current index and checks to see if merges or
 	updates are needed by checking stat() information.
 
 -q::
-        Quiet.  If --refresh finds that the cache needs an update, the
+        Quiet.  If --refresh finds that the index needs an update, the
         default behavior is to error out.  This option makes
         git-update-index continue anyway.
 
 --unmerged::
-        If --refresh finds unmerged changes in the cache, the default 
+        If --refresh finds unmerged changes in the index, the default
         behavior is to error out.  This option makes git-update-index 
         continue anyway.
 
@@ -57,10 +57,10 @@ OPTIONS
 	Ignores missing files during a --refresh
 
 --cacheinfo <mode> <object> <path>::
-	Directly insert the specified info into the cache.
+	Directly insert the specified info into the index.
 	
 --index-info::
-        Read index info from stdin.
+        Read index information from stdin.
 
 --chmod=(+|-)x::
         Set the execute permissions on the updated files.        
@@ -68,7 +68,7 @@ OPTIONS
 --info-only::
 	Do not create objects in the object database for all
 	<file> arguments that follow this flag; just insert
-	their object IDs into the cache.
+	their object IDs into the index.
 
 --force-remove::
 	Remove the file from the index even when the working directory
@@ -106,14 +106,14 @@ OPTIONS
 
 Using --refresh
 ---------------
-'--refresh' does not calculate a new sha1 file or bring the cache
+'--refresh' does not calculate a new sha1 file or bring the index
 up-to-date for mode/content changes. But what it *does* do is to
-"re-match" the stat information of a file with the cache, so that you
+"re-match" the stat information of a file with the index, so that you
-can refresh the cache for a file that hasn't been changed but where
+can refresh the index for a file that hasn't been changed but where
 the stat entry is out of date.
 
 For example, you'd want to do this after doing a "git-read-tree", to link
-up the stat cache details with the proper files.
+up the stat index details with the proper files.
 
 Using --cacheinfo or --info-only
 --------------------------------
@@ -123,7 +123,9 @@ merging.
 
 To pretend you have a file with mode and sha1 at path, say:
 
-   $ git-update-index --cacheinfo mode sha1 path
+----------------
+$ git-update-index --cacheinfo mode sha1 path
+----------------
 
 '--info-only' is used to register files without placing them in the object
 database.  This is useful for status-only repositories.
@@ -134,11 +136,70 @@ in the database but the file isn't available locally.  '--info-only' is
 useful when the file is available, but you do not wish to update the
 object database.
 
+
+Using --index-info
+------------------
+
+`--index-info` is a more powerful mechanism that lets you feed
+multiple entry definitions from the standard input, and designed
+specifically for scripts.  It can take inputs of three formats:
+
+    . mode         SP sha1          TAB path
++
+The first format is what "git-apply --index-info"
+reports, and used to reconstruct a partial tree
+that is used for phony merge base tree when falling
+back on 3-way merge.
+
+    . mode SP type SP sha1          TAB path
++
+The second format is to stuff git-ls-tree output
+into the index file.
+
+    . mode         SP sha1 SP stage TAB path
++
+This format is to put higher order stages into the
+index file and matches git-ls-files --stage output.
+
+To place a higher stage entry to the index, the path should
+first be removed by feeding a mode=0 entry for the path, and
+then feeding necessary input lines in the third format.
+
+For example, starting with this index:
+
+------------
+$ git ls-files -s
+100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0       frotz
+------------
+
+you can feed the following input to `--index-info`:
+
+------------
+$ git update-index --index-info
+0 0000000000000000000000000000000000000000	frotz
+100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
+100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz
+------------
+
+The first line of the input feeds 0 as the mode to remove the
+path; the SHA1 does not matter as long as it is well formatted.
+Then the second and third line feeds stage 1 and stage 2 entries
+for that path.  After the above, we would end up with this:
+
+------------
+$ git ls-files -s
+100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1	frotz
+100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2	frotz
+------------
+
+
 Examples
 --------
 To update and refresh only the files already checked out:
 
-   git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
 
 
 Configuration
@@ -146,12 +207,18 @@ Configuration
 
 The command honors `core.filemode` configuration variable.  If
 your repository is on an filesystem whose executable bits are
-unreliable, this should be set to 'false'.  This causes the
+unreliable, this should be set to 'false' (see gitlink:git-repo-config[1]).
-command to ignore differences in file modes recorded in the
+This causes the command to ignore differences in file modes recorded
-index and the file mode on the filesystem if they differ only on
+in the index and the file mode on the filesystem if they differ only on
 executable bit.   On such an unfortunate filesystem, you may
 need to use `git-update-index --chmod=`.
 
+
+See Also
+--------
+gitlink:git-repo-config[1]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

Documentation/git-update-server-info.txt

@@ -12,17 +12,17 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-A dumb server that does not do on-the-fly pack generations can
+A dumb server that does not do on-the-fly pack generations must
 have some auxiliary information files in $GIT_DIR/info and
 $GIT_OBJECT_DIRECTORY/info directories to help clients discover
-what references and packs the server has and make optimized
+what references and packs the server has.  This command
-pull decisions.  This command generates such auxiliary files.
+generates such auxiliary files.
 
 
 OPTIONS
 -------
 
---force::
+-f|--force::
 	Update the info files from scratch.
 
 

Documentation/git-verify-pack.txt

@@ -8,7 +8,7 @@ git-verify-pack - Validate packed git archive files.
 
 SYNOPSIS
 --------
-'git-verify-pack' [-v] <pack>.idx ...
+'git-verify-pack' [-v] [--] <pack>.idx ...
 
 
 DESCRIPTION
@@ -25,6 +25,8 @@ OPTIONS
 -v::
 	After verifying the pack, show list of objects contained
 	in the pack.
+--::
+	Do not interpret any more arguments as options.
 
 OUTPUT FORMAT
 -------------

Documentation/git-write-tree.txt

@@ -3,7 +3,7 @@ git-write-tree(1)
 
 NAME
 ----
-git-write-tree - Creates a tree object from the current cache
+git-write-tree - Creates a tree object from the current index
 
 
 SYNOPSIS
@@ -12,21 +12,23 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Creates a tree object using the current cache.
+Creates a tree object using the current index.
 
-The cache must be merged.
+The index must be in a fully merged state.
 
-Conceptually, "git-write-tree" sync()s the current directory cache contents
+Conceptually, `git-write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a "git-update-index" phase before you did the
+now, you need to have done a `git-update-index` phase before you did the
-"git-write-tree".
+`git-write-tree`.
+
 
 OPTIONS
 -------
 --missing-ok::
-	Normally "git-write-tree" ensures that the objects referenced by the
+	Normally `git-write-tree` ensures that the objects referenced by the
-	directory exist in the object database.  This option disables this check.
+	directory exist in the object database.  This option disables this
+	check.
 
 Author
 ------

Documentation/git.txt

@@ -8,39 +8,70 @@ git - the stupid content tracker
 
 SYNOPSIS
 --------
-'git-<command>' <args>
+'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
 
 DESCRIPTION
 -----------
+'git' is both a program and a directory content tracker system.
+The program 'git' is just a wrapper to reach the core git programs
+(or a potty if you like, as it's not exactly porcelain but still
+brings your stuff to the plumbing).
 
-This is reference information for the core git commands.
+OPTIONS
+-------
+--version::
+	prints the git suite version that the 'git' program came from.
 
-Before reading this cover to cover, you may want to take a look
+--help::
-at the link:tutorial.html[tutorial] document.
+	prints the synopsis and a list of available commands.
+	If a git command is named this option will bring up the
+	man-page for that command.
 
-The <<Discussion>> section below contains much useful definition and
+--exec-path::
-clarification info - read that first.  And of the commands, I suggest
+	path to wherever your core git programs are installed.
-reading gitlink:git-update-index[1] and
+	This can also be controlled by setting the GIT_EXEC_PATH
-gitlink:git-read-tree[1] first - I wish I had!
+	environment variable. If no path is given 'git' will print
+	the current setting and then exit.
 
-If you are migrating from CVS, link:cvs-migration.html[cvs migration]
+
-document may be helpful after you finish the tutorial.
+NOT LEARNING CORE GIT COMMANDS
+------------------------------
+
+This manual is intended to give complete background information
+and internal workings of git, which may be too much for most
+people.  The <<Discussion>> section below contains much useful
+definition and clarification - read that first.
+
+If you are interested in using git to manage (version control)
+projects, use link:everyday.html[Everyday GIT] as a guide to the
+minimum set of commands you need to know for day-to-day work.
+Most likely, that will get you started, and you can go a long
+way without knowing the low level details too much.
+
+The link:tutorial.html[tutorial] document covers how things
+internally work.
+
+If you are migrating from CVS, link:cvs-migration.html[cvs
+migration] document may be helpful after you finish the
+tutorial.
 
 After you get the general feel from the tutorial and this
 overview page, you may want to take a look at the
 link:howto-index.html[howto] documents.
 
 
-David Greaves <david@dgreaves.com>
+CORE GIT COMMANDS
-08/05/05
+-----------------
+
+If you are writing your own Porcelain, you need to be familiar
+with most of the low level commands --- I suggest starting from
+gitlink:git-update-index[1] and gitlink:git-read-tree[1].
 
-Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
-reflect recent changes.
 
 Commands Overview
 -----------------
 The git commands can helpfully be split into those that manipulate
-the repository, the cache and the working fileset, those that
+the repository, the index and the files in the working tree, those that
 interrogate and compare them, and those that moves objects and
 references between repositories.
 
@@ -59,25 +90,26 @@ gitlink:git-apply[1]::
 	applies it to the working tree.
 
 gitlink:git-checkout-index[1]::
-	Copy files from the cache to the working directory
+	Copy files from the index to the working tree.
 
 gitlink:git-commit-tree[1]::
-	Creates a new commit object
+	Creates a new commit object.
 
 gitlink:git-hash-object[1]::
 	Computes the object ID from a file.
 
-gitlink:git-index-pack.html[1]::
+gitlink:git-index-pack[1]::
-	Build pack index file for an existing packed archive.
+	Build pack idx file for an existing packed archive.
 
 gitlink:git-init-db[1]::
-	Creates an empty git object database
+	Creates an empty git object database, or reinitialize an
+	existing one.
 
 gitlink:git-merge-index[1]::
-	Runs a merge for files needing merging
+	Runs a merge for files needing merging.
 
 gitlink:git-mktag[1]::
-	Creates a tag object
+	Creates a tag object.
 
 gitlink:git-pack-objects[1]::
 	Creates a packed archive of objects.
@@ -86,71 +118,77 @@ gitlink:git-prune-packed[1]::
 	Remove extra objects that are already in pack files.
 
 gitlink:git-read-tree[1]::
-	Reads tree information into the directory cache
+	Reads tree information into the index.
+
+gitlink:git-repo-config[1]::
+	Get and set options in .git/config.
 
 gitlink:git-unpack-objects[1]::
 	Unpacks objects out of a packed archive.
 
 gitlink:git-update-index[1]::
-	Modifies the index or directory cache
+	Registers files in the working tree to the index.
 
 gitlink:git-write-tree[1]::
-	Creates a tree from the current cache
+	Creates a tree from the index.
 
 
 Interrogation commands
 ~~~~~~~~~~~~~~~~~~~~~~
 
 gitlink:git-cat-file[1]::
-	Provide content or type information for repository objects
+	Provide content or type/size information for repository objects.
 
 gitlink:git-diff-index[1]::
-	Compares content and mode of blobs between the cache and repository
+	Compares content and mode of blobs between the index and repository.
 
 gitlink:git-diff-files[1]::
-	Compares files in the working tree and the cache
+	Compares files in the working tree and the index.
 
 gitlink:git-diff-stages[1]::
-	Compares two "merge stages" in the index file.
+	Compares two "merge stages" in the index.
 
 gitlink:git-diff-tree[1]::
-	Compares the content and mode of blobs found via two tree objects
+	Compares the content and mode of blobs found via two tree objects.
 
 gitlink:git-fsck-objects[1]::
-	Verifies the connectivity and validity of the objects in the database
+	Verifies the connectivity and validity of the objects in the database.
 
 gitlink:git-ls-files[1]::
-	Information about files in the cache/working directory
+	Information about files in the index and the working tree.
 
 gitlink:git-ls-tree[1]::
-	Displays a tree object in human readable form
+	Displays a tree object in human readable form.
 
 gitlink:git-merge-base[1]::
-	Finds as good a common ancestor as possible for a merge
+	Finds as good common ancestors as possible for a merge.
 
 gitlink:git-name-rev[1]::
-	Find symbolic names for given revs
+	Find symbolic names for given revs.
+
+gitlink:git-pack-redundant[1]::
+	Find redundant pack files.
 
 gitlink:git-rev-list[1]::
-	Lists commit objects in reverse chronological order
+	Lists commit objects in reverse chronological order.
 
 gitlink:git-show-index[1]::
 	Displays contents of a pack idx file.
 
 gitlink:git-tar-tree[1]::
-	Creates a tar archive of the files in the named tree
+	Creates a tar archive of the files in the named tree object.
 
 gitlink:git-unpack-file[1]::
-	Creates a temporary file with a blob's contents
+	Creates a temporary file with a blob's contents.
 
 gitlink:git-var[1]::
-	Displays a git logical variable
+	Displays a git logical variable.
 
 gitlink:git-verify-pack[1]::
-	Validates packed git archive files
+	Validates packed git archive files.
 
-The interrogate commands may create files - and you can force them to
+In general, the interrogate commands do not touch the files in
-touch the working file set - but in general they don't
+the working tree.
 
 
 Synching repositories
@@ -158,19 +196,24 @@ Synching repositories
 
 gitlink:git-clone-pack[1]::
 	Clones a repository into the current repository (engine
-	for ssh and local transport)
+	for ssh and local transport).
 
 gitlink:git-fetch-pack[1]::
-	Updates from a remote repository.
+	Updates from a remote repository (engine for ssh and
+	local transport).
 
 gitlink:git-http-fetch[1]::
-	Downloads a remote git repository via HTTP
+	Downloads a remote git repository via HTTP by walking
+	commit chain.
 
 gitlink:git-local-fetch[1]::
-	Duplicates another git repository on a local system
+	Duplicates another git repository on a local system by
+	walking commit chain.
 
 gitlink:git-peek-remote[1]::
-	Lists references on a remote repository using upload-pack protocol.
+	Lists references on a remote repository using
+	upload-pack protocol (engine for ssh and local
+	transport).
 
 gitlink:git-receive-pack[1]::
 	Invoked by 'git-send-pack' to receive what is pushed to it.
@@ -178,14 +221,18 @@ gitlink:git-receive-pack[1]::
 gitlink:git-send-pack[1]::
 	Pushes to a remote repository, intelligently.
 
+gitlink:git-http-push[1]::
+	Push missing objects using HTTP/DAV.
+
 gitlink:git-shell[1]::
 	Restricted shell for GIT-only SSH access.
 
 gitlink:git-ssh-fetch[1]::
-	Pulls from a remote repository over ssh connection
+	Pulls from a remote repository over ssh connection by
+	walking commit chain.
 
 gitlink:git-ssh-upload[1]::
-	Helper "server-side" program used by git-ssh-fetch
+	Helper "server-side" program used by git-ssh-fetch.
 
 gitlink:git-update-server-info[1]::
 	Updates auxiliary information on a dumb server to help
@@ -200,16 +247,16 @@ Porcelain-ish Commands
 ----------------------
 
 gitlink:git-add[1]::
-	Add paths to the index file.
+	Add paths to the index.
 
 gitlink:git-am[1]::
 	Apply patches from a mailbox, but cooler.
 
 gitlink:git-applymbox[1]::
-	Apply patches from a mailbox.
+	Apply patches from a mailbox, original version by Linus.
 
 gitlink:git-bisect[1]::
-	Find the change that introduced a bug.
+	Find the change that introduced a bug by binary search.
 
 gitlink:git-branch[1]::
 	Create and Show branches.
@@ -236,7 +283,7 @@ gitlink:git-format-patch[1]::
 	Prepare patches for e-mail submission.
 
 gitlink:git-grep[1]::
-	Print lines matching a pattern
+	Print lines matching a pattern.
 
 gitlink:git-log[1]::
 	Shows commit logs.
@@ -250,9 +297,6 @@ gitlink:git-merge[1]::
 gitlink:git-mv[1]::
 	Move or rename a file, a directory, or a symlink.
 
-gitlink:git-octopus[1]::
-	Merge more than two commits.
-
 gitlink:git-pull[1]::
 	Fetch from and merge with a remote repository.
 
@@ -260,10 +304,7 @@ gitlink:git-push[1]::
 	Update remote refs along with associated objects.
 
 gitlink:git-rebase[1]::
-	Rebase local commits to new upstream head.
+	Rebase local commits to the updated upstream head.
-
-gitlink:git-rename[1]::
-	Rename files and directories.
 
 gitlink:git-repack[1]::
 	Pack unpacked objects in a repository.
@@ -304,16 +345,22 @@ gitlink:git-archimport[1]::
 	Import an arch repository into git.
 
 gitlink:git-convert-objects[1]::
-	Converts old-style git repository
+	Converts old-style git repository.
 
 gitlink:git-cvsimport[1]::
 	Salvage your data out of another SCM people love to hate.
 
+gitlink:git-cvsexportcommit[1]::
+	Export a single commit to a CVS checkout.
+
+gitlink:git-lost-found[1]::
+	Recover lost refs that luckily have not yet been pruned.
+
 gitlink:git-merge-one-file[1]::
-	The standard helper program to use with "git-merge-index"
+	The standard helper program to use with `git-merge-index`.
 
 gitlink:git-prune[1]::
-	Prunes all unreachable objects from the object database
+	Prunes all unreachable objects from the object database.
 
 gitlink:git-relink[1]::
 	Hardlink common objects in local repositories.
@@ -325,10 +372,10 @@ gitlink:git-sh-setup[1]::
 	Common git shell script setup code.
 
 gitlink:git-symbolic-ref[1]::
-	Read and modify symbolic refs
+	Read and modify symbolic refs.
 
 gitlink:git-tag[1]::
-	An example script to create a tag object signed with GPG
+	An example script to create a tag object signed with GPG.
 
 gitlink:git-update-ref[1]::
 	Update the object name stored in a ref safely.
@@ -352,16 +399,19 @@ gitlink:git-get-tar-commit-id[1]::
 	Extract commit ID from an archive created using git-tar-tree.
 
 gitlink:git-mailinfo[1]::
-	Extracts patch from a single e-mail message.
+	Extracts patch and authorship information from a single
+	e-mail message, optionally transliterating the commit
+	message into utf-8.
 
 gitlink:git-mailsplit[1]::
-	git-mailsplit.
+	A stupid program to split UNIX mbox format mailbox into
+	individual pieces of e-mail.
 
 gitlink:git-patch-id[1]::
 	Compute unique ID for a patch.
 
 gitlink:git-parse-remote[1]::
-	Routines to help parsing $GIT_DIR/remotes/
+	Routines to help parsing `$GIT_DIR/remotes/` files.
 
 gitlink:git-request-pull[1]::
 	git-request-pull.
@@ -372,7 +422,7 @@ gitlink:git-rev-parse[1]::
 gitlink:git-send-email[1]::
 	Send patch e-mails out of "format-patch --mbox" output.
 
-gitlink:git-symbolic-refs[1]::
+gitlink:git-symbolic-ref[1]::
 	Read and modify symbolic refs.
 
 gitlink:git-stripspace[1]::
@@ -383,22 +433,20 @@ Commands not yet documented
 ---------------------------
 
 gitlink:gitk[1]::
-	gitk.
+	The gitk repository browser.
 
 
 Configuration Mechanism
 -----------------------
 
-Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
+Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 is used to hold per-repository configuration options.  It is a
 simple text file modelled after `.ini` format familiar to some
 people.  Here is an example:
 
 ------------
 #
-# This is the config file, and
+# A '#' or ';' character indicates a comment.
-# a '#' or ';' character indicates
-# a comment
 #
 
 ; core variables
@@ -420,30 +468,30 @@ their operation accordingly.
 Identifier Terminology
 ----------------------
 <object>::
-	Indicates the sha1 identifier for any type of object
+	Indicates the object name for any type of object.
 
 <blob>::
-	Indicates a blob object sha1 identifier
+	Indicates a blob object name.
 
 <tree>::
-	Indicates a tree object sha1 identifier
+	Indicates a tree object name.
 
 <commit>::
-	Indicates a commit object sha1 identifier
+	Indicates a commit object name.
 
 <tree-ish>::
-	Indicates a tree, commit or tag object sha1 identifier.  A
+	Indicates a tree, commit or tag object name.  A
 	command that takes a <tree-ish> argument ultimately wants to
 	operate on a <tree> object but automatically dereferences
 	<commit> and <tag> objects that point at a <tree>.
 
 <type>::
 	Indicates that an object type is required.
-	Currently one of: blob/tree/commit/tag
+	Currently one of: `blob`, `tree`, `commit`, or `tag`.
 
 <file>::
-	Indicates a filename - always relative to the root of
+	Indicates a filename - almost always relative to the
-	the tree structure GIT_INDEX_FILE describes.
+	root of the tree structure `GIT_INDEX_FILE` describes.
 
 Symbolic Identifiers
 --------------------
@@ -451,17 +499,20 @@ Any git command accepting any <object> can also use the following
 symbolic notation:
 
 HEAD::
-	indicates the head of the repository (ie the contents of
+	indicates the head of the current branch (i.e. the
-	`$GIT_DIR/HEAD`)
+	contents of `$GIT_DIR/HEAD`).
+
 <tag>::
-	a valid tag 'name'+
+	a valid tag 'name'
-	(ie the contents of `$GIT_DIR/refs/tags/<tag>`)
+	(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
+
 <head>::
-	a valid head 'name'+
+	a valid head 'name'
-	(ie the contents of `$GIT_DIR/refs/heads/<head>`)
+	(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
+
 <snap>::
-	a valid snapshot 'name'+
+	a valid snapshot 'name'
-	(ie the contents of `$GIT_DIR/refs/snap/<snap>`)
+	(i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
 
 
 File/Directory Structure
@@ -470,7 +521,7 @@ File/Directory Structure
 Please see link:repository-layout.html[repository layout] document.
 
 Higher level SCMs may provide and manage additional information in the
-GIT_DIR.
+`$GIT_DIR`.
 
 
 Terminology
@@ -486,12 +537,12 @@ The git Repository
 ~~~~~~~~~~~~~~~~~~
 These environment variables apply to 'all' core git commands. Nb: it
 is worth noting that they may be used/overridden by SCMS sitting above
-git so take care if using Cogito etc
+git so take care if using Cogito etc.
 
 'GIT_INDEX_FILE'::
 	This environment allows the specification of an alternate
-	cache/index file. If not specified, the default of
+	index file. If not specified, the default of `$GIT_DIR/index`
-	`$GIT_DIR/index` is used.
+	is used.
 
 'GIT_OBJECT_DIRECTORY'::
 	If the object storage directory is specified via this
@@ -507,9 +558,9 @@ git so take care if using Cogito etc
 	written to these directories.
 
 'GIT_DIR'::
-	If the 'GIT_DIR' environment variable is set then it specifies
+	If the 'GIT_DIR' environment variable is set then it
-	a path to use instead of `./.git` for the base of the
+	specifies a path to use instead of the default `.git`
-	repository.
+	for the base of the repository.
 
 git Commits
 ~~~~~~~~~~~
@@ -533,13 +584,18 @@ Discussion[[Discussion]]
 ------------------------
 include::../README[]
 
-Author
+Authors
-------
+-------
-Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
+* git's founding father is Linus Torvalds <torvalds@osdl.org>.
+* The current git nurse is Junio C Hamano <junkio@cox.net>.
+* The git potty was written by Andres Ericsson <ae@op5.se>.
+* General upbringing is handled by the git-list <git@vger.kernel.org>.
 
 Documentation
 --------------
-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+The documentation for git suite was started by David Greaves
+<david@dgreaves.com>, and later enhanced greatly by the
+contributors on the git-list <git@vger.kernel.org>.
 
 GIT
 ---

Documentation/glossary.txt

@@ -19,8 +19,8 @@ hash::
 	In git's context, synonym to object name.
 
 object database::
-	Stores a set of "objects", and an individial object is identified
+	Stores a set of "objects", and an individual object is identified
-	by its object name. The object usually live in $GIT_DIR/objects/.
+	by its object name. The objects usually live in `$GIT_DIR/objects/`.
 
 blob object::
 	Untyped object, e.g. the contents of a file.
@@ -43,14 +43,14 @@ DAG::
 
 index::
 	A collection of files with stat information, whose contents are
-	stored as objects. The cache is a stored version of your working
+	stored as objects. The index is a stored version of your working
 	tree. Truth be told, it can also contain a second, and even a third
 	version of a working tree, which are used when merging.
 
 index entry::
 	The information regarding a particular file, stored in the index.
 	An index entry can be unmerged, if a merge was started, but not
-	yet finished (i.e. if the cache contains multiple versions of
+	yet finished (i.e. if the index contains multiple versions of
 	that file).
 
 unmerged index:
@@ -75,7 +75,7 @@ checkout::
 	stored in the object database.
 
 commit::
-	As a verb: The action of storing the current state of the cache in the
+	As a verb: The action of storing the current state of the index in the
 	object database. The result is a revision.
 	As a noun: Short hand for commit object.
 
@@ -109,15 +109,26 @@ head::
 branch::
 	A non-cyclical graph of revisions, i.e. the complete history of
 	a particular revision, which is called the branch head. The
-	branch heads are stored in $GIT_DIR/refs/heads/.
+	branch heads are stored in `$GIT_DIR/refs/heads/`.
+
+master::
+	The default branch. Whenever you create a git repository, a branch
+	named "master" is created, and becomes the active branch. In most
+	cases, this contains the local development.
+
+origin::
+	The default upstream branch. Most projects have one upstream
+	project which they track, and by default 'origin' is used for
+	that purpose.  New updates from upstream will be fetched into
+	this branch; you should never commit to it yourself.
 
 ref::
 	A 40-byte hex representation of a SHA1 pointing to a particular
-	object. These may be stored in $GIT_DIR/refs/.
+	object. These may be stored in `$GIT_DIR/refs/`.
 
 head ref::
 	A ref pointing to a head. Often, this is abbreviated to "head".
-	Head refs are stored in $GIT_DIR/refs/heads/.
+	Head refs are stored in `$GIT_DIR/refs/heads/`.
 
 tree-ish::
 	A ref pointing to either a commit object, a tree object, or a
@@ -125,7 +136,7 @@ tree-ish::
 
 ent::
 	Favorite synonym to "tree-ish" by some total geeks. See
-	http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth
+	`http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth
 	explanation.
 
 tag object::
@@ -137,7 +148,7 @@ tag object::
 tag::
 	A ref pointing to a tag or commit object. In contrast to a head,
 	a tag is not changed by a commit. Tags (not tag objects) are
-	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
+	stored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with
 	a Lisp tag (which is called object type in git's context).
 	A tag is most typically used to mark a particular point in the
 	commit ancestry chain.

Documentation/hooks.txt

@@ -111,6 +111,10 @@ Another use suggested on the mailing list is to use this hook to
 implement access control which is finer grained than the one
 based on filesystem group.
 
+The standard output of this hook is sent to /dev/null; if you
+want to report something to the git-send-pack on the other end,
+you can redirect your output to your stderr.
+
 post-update
 -----------
 
@@ -125,3 +129,7 @@ the outcome of `git-receive-pack`.
 The default post-update hook, when enabled, runs
 `git-update-server-info` to keep the information used by dumb
 transport up-to-date.
+
+The standard output of this hook is sent to /dev/null; if you
+want to report something to the git-send-pack on the other end,
+you can redirect your output to your stderr.

Documentation/howto/isolate-bugs-with-bisect.txt

@@ -0,0 +1,65 @@
+From:	Linus Torvalds <torvalds () osdl ! org>
+To:	git@vger.kernel.org
+Date:	2005-11-08 1:31:34
+Subject: Real-life kernel debugging scenario
+Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform
+	bug isolation on a repository where "good" and "bad" revisions are known
+	in order to identify a suspect commit.
+
+
+How To Use git-bisect To Isolate a Bogus Commit
+===============================================
+
+The way to use "git bisect" couldn't be easier.
+
+Figure out what the oldest bad state you know about is (that's usually the 
+head of "master", since that's what you just tried to boot and failed at). 
+Also, figure out the most recent known-good commit (usually the _previous_ 
+kernel you ran: and if you've only done a single "pull" in between, it 
+will be ORIG_HEAD).
+
+Then do
+
+	git bisect start
+	git bisect bad master		<- mark "master" as the bad state
+	git bisect good ORIG_HEAD	<- mark ORIG_HEAD as good (or
+					   whatever other known-good 
+					   thing you booted last)
+
+and at this point "git bisect" will churn for a while, and tell you what 
+the mid-point between those two commits are, and check that state out as 
+the head of the bew "bisect" branch.
+
+Compile and reboot.
+
+If it's good, just do
+
+	git bisect good		<- mark current head as good
+
+otherwise, reboot into a good kernel instead, and do (surprise surprise, 
+git really is very intuitive):
+
+	git bisect bad		<- mark current head as bad
+
+and whatever you do, git will select a new half-way point. Do this for a 
+while, until git tells you exactly which commit was the first bad commit. 
+That's your culprit.
+
+It really works wonderfully well, except for the case where there was 
+_another_ commit that broke something in between, like introduced some 
+stupid compile error. In that case you should not mark that commit good or 
+bad: you should try to find another commit close-by, and do a "git reset 
+--hard <newcommit>" to try out _that_ commit instead, and then test that 
+instead (and mark it good or bad).
+
+You can do "git bisect visualize" while you do all this to see what's 
+going on by starting up gitk on the bisection range.
+
+Finally, once you've figured out exactly which commit was bad, you can 
+then go back to the master branch, and try reverting just that commit:
+
+	git checkout master
+	git revert <bad-commit-id>
+
+to verify that the top-of-kernel works with that single commit reverted.
+

Documentation/howto/rebase-and-edit.txt

@@ -63,7 +63,7 @@ And then, you can just remove the broken branch if you decide you really
 don't want it:
 
 	# remove 'broken' branch
-	rm .git/refs/heads/broken
+	git branch -d broken
 
 	# Prune old objects if you're really really sure
 	git prune

Documentation/howto/rebase-from-internal-branch.txt

@@ -40,10 +40,7 @@ So I started from master, made a bunch of edits, and committed:
     $ git checkout master
     $ cd Documentation; ed git.txt ...
     $ cd ..; git add Documentation/*.txt
-    $ git commit -s -v
+    $ git commit -s
-
-NOTE.  The -v flag to commit is a handy way to make sure that
-your additions are not introducing bogusly formatted lines.
 
 After the commit, the ancestry graph would look like this:
 
@@ -98,7 +95,7 @@ to do cherrypicking using only the core GIT tools.
 Let's go back to the earlier picture, with different labels.
 
 You, as an individual developer, cloned upstream repository and
-amde a couple of commits on top of it.
+made a couple of commits on top of it.
 
                               *your "master" head
    upstream --> #1 --> #2 --> #3

Documentation/howto/rebuild-from-update-hook.txt

@@ -10,7 +10,7 @@ The pages under http://www.kernel.org/pub/software/scm/git/docs/
 are built from Documentation/ directory of the git.git project
 and needed to be kept up-to-date.  The www.kernel.org/ servers
 are mirrored and I was told that the origin of the mirror is on
-the machine master.kernel.org, on which I was given an account
+the machine $some.kernel.org, on which I was given an account
 when I took over git maintainership from Linus.
 
 The directories relevant to this how-to are these two:
@@ -63,7 +63,7 @@ like this:
     EOF
     $ chmod +x /pub/scm/git/git.git/hooks/post-update
 
-There are three things worth mentioning:
+There are four things worth mentioning:
 
  - The update-hook is run after the repository accepts a "git
    push", under my user privilege.  It is given the full names
@@ -77,6 +77,10 @@ There are three things worth mentioning:
    pull" it does into $HOME/doc-git/docgen/ repository would not
    work correctly.
 
+ - The stdout of update hook script is not connected to git
+   push; I run the heavy part of the command inside "at", to
+   receive the execution report via e-mail.
+
  - This is still crude and does not protect against simultaneous
    make invocations stomping on each other.  I would need to add
    some locking mechanism for this.

Documentation/howto/revert-branch-rebase.txt

@@ -153,7 +153,8 @@ Everything is in the good order.  I do not need the temporary branch
 nor tag anymore, so remove them:
 
 ------------------------------------------------
-$ rm -f .git/refs/tags/pu-anchor .git/refs/heads/revert-c99
+$ rm -f .git/refs/tags/pu-anchor 
+$ git branch -d revert-c99
 ------------------------------------------------
 
 It was an emergency fix, so we might as well merge it into the

Documentation/howto/update-hook-example.txt

@@ -0,0 +1,172 @@
+From: Junio C Hamano <junkio@cox.net> and Carl Baldwin <cnb@fc.hp.com>
+Subject: control access to branches.
+Date: Thu, 17 Nov 2005 23:55:32 -0800
+Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net>
+Abstract: An example hooks/update script is presented to
+ implement repository maintenance policies, such as who can push
+ into which branch and who can make a tag.
+
+When your developer runs git-push into the repository,
+git-receive-pack is run (either locally or over ssh) as that
+developer, so is hooks/update script.  Quoting from the relevant
+section of the documentation:
+
+    Before each ref is updated, if $GIT_DIR/hooks/update file exists
+    and executable, it is called with three parameters:
+
+           $GIT_DIR/hooks/update refname sha1-old sha1-new
+
+    The refname parameter is relative to $GIT_DIR; e.g. for the
+    master head this is "refs/heads/master".  Two sha1 are the
+    object names for the refname before and after the update.  Note
+    that the hook is called before the refname is updated, so either
+    sha1-old is 0{40} (meaning there is no such ref yet), or it
+    should match what is recorded in refname.
+
+So if your policy is (1) always require fast-forward push
+(i.e. never allow "git-push repo +branch:branch"), (2) you
+have a list of users allowed to update each branch, and (3) you
+do not let tags to be overwritten, then you can use something
+like this as your hooks/update script.
+
+[jc: editorial note.  This is a much improved version by Carl
+since I posted the original outline]
+
+-- >8 -- beginning of script -- >8 --
+
+#!/bin/bash
+
+umask 002
+
+# If you are having trouble with this access control hook script
+# you can try setting this to true.  It will tell you exactly
+# why a user is being allowed/denied access.
+
+verbose=false
+
+# Default shell globbing messes things up downstream
+GLOBIGNORE=*
+
+function grant {
+  $verbose && echo >&2 "-Grant-		$1"
+  echo grant
+  exit 0
+}
+
+function deny {
+  $verbose && echo >&2 "-Deny-		$1"
+  echo deny
+  exit 1
+}
+
+function info {
+  $verbose && echo >&2 "-Info-		$1"
+}
+
+# Implement generic branch and tag policies.
+# - Tags should not be updated once created.
+# - Branches should only be fast-forwarded.
+case "$1" in
+  refs/tags/*)
+    [ -f "$GIT_DIR/$1" ] &&
+    deny >/dev/null "You can't overwrite an existing tag"
+    ;;
+  refs/heads/*)
+    # No rebasing or rewinding
+    if expr "$2" : '0*$' >/dev/null; then
+      info "The branch '$1' is new..."
+    else
+      # updating -- make sure it is a fast forward
+      mb=$(git-merge-base "$2" "$3")
+      case "$mb,$2" in
+        "$2,$mb") info "Update is fast-forward" ;;
+        *)        deny >/dev/null  "This is not a fast-forward update." ;;
+      esac
+    fi
+    ;;
+  *)
+    deny >/dev/null \
+    "Branch is not under refs/heads or refs/tags.  What are you trying to do?"
+    ;;
+esac
+
+# Implement per-branch controls based on username
+allowed_users_file=$GIT_DIR/info/allowed-users
+username=$(id -u -n)
+info "The user is: '$username'"
+
+if [ -f "$allowed_users_file" ]; then
+  rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' |
+    while read head_pattern user_patterns; do
+      matchlen=$(expr "$1" : "$head_pattern")
+      if [ "$matchlen" == "${#1}" ]; then
+        info "Found matching head pattern: '$head_pattern'"
+        for user_pattern in $user_patterns; do
+          info "Checking user: '$username' against pattern: '$user_pattern'"
+          matchlen=$(expr "$username" : "$user_pattern")
+          if [ "$matchlen" == "${#username}" ]; then
+            grant "Allowing user: '$username' with pattern: '$user_pattern'"
+          fi
+        done
+        deny "The user is not in the access list for this branch"
+      fi
+    done
+  )
+  case "$rc" in
+    grant) grant >/dev/null "Granting access based on $allowed_users_file" ;;
+    deny)  deny  >/dev/null "Denying  access based on $allowed_users_file" ;;
+    *) ;;
+  esac
+fi
+
+allowed_groups_file=$GIT_DIR/info/allowed-groups
+groups=$(id -G -n)
+info "The user belongs to the following groups:"
+info "'$groups'"
+
+if [ -f "$allowed_groups_file" ]; then
+  rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' |
+    while read head_pattern group_patterns; do
+      matchlen=$(expr "$1" : "$head_pattern")
+      if [ "$matchlen" == "${#1}" ]; then
+        info "Found matching head pattern: '$head_pattern'"
+        for group_pattern in $group_patterns; do
+          for groupname in $groups; do
+            info "Checking group: '$groupname' against pattern: '$group_pattern'"
+            matchlen=$(expr "$groupname" : "$group_pattern")
+            if [ "$matchlen" == "${#groupname}" ]; then
+              grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
+            fi
+          done
+        done
+        deny "None of the user's groups are in the access list for this branch"
+      fi
+    done
+  )
+  case "$rc" in
+    grant) grant >/dev/null "Granting access based on $allowed_groups_file" ;;
+    deny)  deny  >/dev/null "Denying  access based on $allowed_groups_file" ;;
+    *) ;;
+  esac
+fi
+
+deny >/dev/null "There are no more rules to check.  Denying access"
+
+-- >8 -- end of script -- >8 --
+
+This uses two files, $GIT_DIR/info/allowed-users and
+allowed-groups, to describe which heads can be pushed into by
+whom.  The format of each file would look like this:
+
+	refs/heads/master	junio
+        refs/heads/cogito$	pasky
+	refs/heads/bw/		linus
+        refs/heads/tmp/		*
+        refs/tags/v[0-9]*	junio
+
+With this, Linus can push or create "bw/penguin" or "bw/zebra"
+or "bw/panda" branches, Pasky can do only "cogito", and JC can
+do master branch and make versioned tags.  And anybody can do
+tmp/blah branches.
+
+------------

Documentation/howto/using-topic-branches.txt

@@ -9,7 +9,7 @@ GIT as a Linux subsystem maintainer.
 
 -Tony
 
-Last updated w.r.t. GIT 0.99.5
+Last updated w.r.t. GIT 0.99.9f
 
 Linux subsystem maintenance using GIT
 -------------------------------------
@@ -31,7 +31,7 @@ test tree and then pull to the release tree as that would leave trivial
 patches blocked in the test tree waiting for complex changes to accumulate
 enough test time to graduate.
 
-Back in the BitKeeper days I achieved this my creating small forests of
+Back in the BitKeeper days I achieved this by creating small forests of
 temporary trees, one tree for each logical grouping of patches, and then
 pulling changes from these trees first to the test tree, and then to the
 release tree.  At first I replicated this in GIT, but then I realised
@@ -42,7 +42,7 @@ So here is the step-by-step guide how this all works for me.
 
 First create your work tree by cloning Linus's public tree:
 
- $ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
 
 Change directory into the cloned tree you just created
 
@@ -52,7 +52,7 @@ Set up a remotes file so that you can fetch the latest from Linus' master
 branch into a local branch named "linus":
 
  $ cat > .git/remotes/linus
- URL: rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+ URL: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
  Pull: master:linus
  ^D
 
@@ -89,8 +89,8 @@ out at the current tip of the linus branch.
 
 These can be easily kept up to date by merging from the "linus" branch:
 
- $ git checkout test && git resolve test linus "Auto-update from upstream"
+ $ git checkout test && git merge "Auto-update from upstream" test linus
- $ git checkout release && git resolve release linus "Auto-update from upstream"
+ $ git checkout release && git merge "Auto-update from upstream" release linus
 
 Set up so that you can push upstream to your public tree (you need to
 log-in to the remote system and create an empty tree there before the
@@ -128,7 +128,7 @@ commit to this branch.
 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 resolve test speed-up-spinlocks "Pull speed-up-spinlock changes"
+ $ git checkout test && git merge "Pull speed-up-spinlock changes" test 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.
@@ -138,7 +138,7 @@ 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 resolve release speed-up-spinlocks "Pull speed-up-spinlock changes"
+ $ git checkout release && git merge "Pull speed-up-spinlock changes" release 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
@@ -166,7 +166,7 @@ output from:
 
 is empty.  At this point the branch can be deleted:
 
- $ rm .git/refs/heads/branchname
+ $ 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
@@ -190,7 +190,7 @@ Here are some of the scripts that I use to simplify all this even further.
 
 case "$1" in
 test|release)
-	git checkout $1 && git resolve $1 linus "Auto-update from upstream"
+	git checkout $1 && git merge "Auto-update from upstream" $1 linus
 	;;
 linus)
 	before=$(cat .git/refs/heads/linus)
@@ -231,7 +231,7 @@ test|release)
 		echo $1 already merged into $2 1>&2
 		exit 1
 	fi
-	git checkout $2 && git resolve $2 $1 "Pull $1 into $2 branch"
+	git checkout $2 && git merge "Pull $1 into $2 branch" $2 $1
 	;;
 *)
 	usage

Documentation/install-webdoc.sh

@@ -2,7 +2,7 @@
 
 T="$1"
 
-for h in *.html howto/*.txt howto/*.html
+for h in *.html *.txt howto/*.txt howto/*.html
 do
 	diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" || {
 		echo >&2 "# install $h $T/$h"
@@ -12,7 +12,7 @@ do
 	}
 done
 strip_leading=`echo "$T/" | sed -e 's|.|.|g'`
-for th in "$T"/*.html "$T"/howto/*.txt "$T"/howto/*.html
+for th in "$T"/*.html "$T"/*.txt "$T"/howto/*.txt "$T"/howto/*.html
 do
 	h=`expr "$th" : "$strip_leading"'\(.*\)'`
 	case "$h" in

Documentation/merge-options.txt

@@ -0,0 +1,16 @@
+-n, \--no-summary::
+	Do not show diffstat at the end of the merge.
+
+--no-commit::
+	Perform the merge but pretend the merge failed and do
+	not autocommit, to give the user a chance to inspect and
+	further tweak the merge result before committing.
+
+
+-s <strategy>, \--strategy=<strategy>::
+	Use the given merge strategy; can be supplied more than
+	once to specify them in the order they should be tried.
+	If there is no `-s` option, a built-in list of strategies
+	is used instead (`git-merge-recursive` when merging a single
+	head, `git-merge-octopus` otherwise).
+

Documentation/merge-pull-opts.txt

@@ -1,14 +0,0 @@
--n, --no-summary::
-	Do not show diffstat at the end of the merge.
-
---no-commit::
-	Perform the merge but pretend the merge failed and do
-	not autocommit, to give the user a chance to inspect and
-	further tweak the merge result before committing.
-
--s <strategy>::
-	use that merge strategy; can be given more than once to
-	specify them in the order they should be tried.  If
-	there is no `-s` option, built-in list of strategies is
-	used instead (`git-merge-resolve` when merging a single
-	head, `git-merge-octopus` otherwise).

Documentation/merge-strategies.txt

@@ -0,0 +1,35 @@
+MERGE STRATEGIES
+----------------
+
+resolve::
+	This can only resolve two heads (i.e. the current branch
+	and another branch you pulled from) using 3-way merge
+	algorithm.  It tries to carefully detect criss-cross
+	merge ambiguities and is considered generally safe and
+	fast.
+
+recursive::
+	This can only resolve two heads using 3-way merge
+	algorithm.  When there are more than one common
+	ancestors that can be used for 3-way merge, it creates a
+	merged tree of the common ancestors and uses that as
+	the reference tree for the 3-way merge.  This has been
+	reported to result in fewer merge conflicts without
+	causing mis-merges by tests done on actual merge commits
+	taken from Linux 2.6 kernel development history.
+	Additionally this can detect and handle merges involving
+	renames.  This is the default merge strategy when
+	pulling or merging one branch.
+
+octopus::
+	This resolves more than two-head case, but refuses to do
+	complex merge that needs manual resolution.  It is
+	primarily meant to be used for bundling topic branch
+	heads together.  This is the default merge strategy when
+	pulling or merging more than one branches.
+
+ours::
+	This resolves any number of heads, but the result of the
+	merge is always the current branch head.  It is meant to
+	be used to supersede old development history of side
+	branches.

Documentation/pull-fetch-param.txt

@@ -5,11 +5,31 @@
 	to name the remote repository:
 +
 ===============================================================
-- Rsync URL:		rsync://remote.machine/path/to/repo.git/
+- rsync://host.xz/path/to/repo.git/
-- HTTP(s) URL:		http://remote.machine/path/to/repo.git/
+- http://host.xz/path/to/repo.git/
-- git URL:		git://remote.machine/path/to/repo.git/
+- https://host.xz/path/to/repo.git/
-			or remote.machine:/path/to/repo.git/
+- git://host.xz/path/to/repo.git/
-- Local directory:	/path/to/repo.git/
+- git://host.xz/~user/path/to/repo.git/
+- ssh://host.xz/path/to/repo.git/
+- ssh://host.xz/~user/path/to/repo.git/
+- ssh://host.xz/~/path/to/repo.git
+===============================================================
++
+SSH Is the default transport protocol and also supports an
+scp-like syntax.  Both syntaxes support username expansion,
+as does the native git protocol. The following three are
+identical to the last three above, respectively:
++
+===============================================================
+- host.xz:/path/to/repo.git/
+- host.xz:~user/path/to/repo.git/
+- host.xz:path/to/repo.git
+===============================================================
++
+To sync with a local directory, use:
++
+===============================================================
+- /path/to/repo.git/
 ===============================================================
 +
 In addition to the above, as a short-hand, the name of a
@@ -82,14 +102,19 @@ must know this is the expected usage pattern for a branch.
 [NOTE]
 You never do your own development on branches that appear
 on the right hand side of a <refspec> colon on `Pull:` lines;
-they are to be updated by `git-fetch`.  The corollary is that
+they are to be updated by `git-fetch`.  If you intend to do
-a local branch should be introduced and named on a <refspec>
+development derived from a remote branch `B`, have a `Pull:`
-right-hand-side if you intend to do development derived from
+line to track it (i.e. `Pull: B:remote-B`), and have a separate
-that branch.
+branch `my-B` to do your development on top of it.  The latter
-This leads to the common `Pull: master:origin` mapping of a
+is created by `git branch my-B remote-B` (or its equivalent `git
-remote `master` branch to a local `origin` branch, which
+checkout -b my-B remote-B`).  Run `git fetch` to keep track of
-is then merged to a local development branch, again typically
+the progress of the remote side, and when you see something new
-named `master`.
+on the remote branch, merge it into your development branch with
+`git pull . remote-B`, while you are on `my-B` branch.
+The common `Pull: master:origin` mapping of a remote `master`
+branch to a local `origin` branch, which is then merged to a
+local development branch, again typically named `master`, is made
+when you run `git clone` for you to follow this pattern.
 +
 [NOTE]
 There is a difference between listing multiple <refspec>

Documentation/repository-layout.txt

@@ -21,7 +21,7 @@ outside world but sometimes useful for private repository.
 . You can be using `objects/info/alternates` mechanism, or
 `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
 objects from other object stores.  A repository with this kind
-of incompete object store is not suitable to be published for
+of incomplete object store is not suitable to be published for
 use with dumb transports but otherwise is OK as long as
 `objects/info/alternates` points at the right object stores
 it borrows from.
@@ -106,7 +106,7 @@ info/refs::
 	up-to-date if the repository is published for dumb
 	transports.  The `git-receive-pack` command, which is
 	run on a remote repository when you `git push` into it,
-	runs `hooks/update` hook to help you achive this.
+	runs `hooks/update` hook to help you achieve this.
 
 info/grafts::
 	This file records fake commit ancestry information, to

Documentation/sort_glossary.pl

@@ -42,7 +42,6 @@ sub no_spaces ($) {
 
 print 'GIT Glossary
 ============
-Aug 2005
 
 This list is sorted alphabetically:
 

Documentation/technical/pack-protocol.txt

@@ -1,3 +1,6 @@
+Pack transfer protocols
+=======================
+
 There are two Pack push-pull protocols.
 
 upload-pack (S) | fetch/clone-pack (C) protocol:

Documentation/tutorial.txt

@@ -18,7 +18,20 @@ doing.
 The core git is often called "plumbing", with the prettier user
 interfaces on top of it called "porcelain". You may not want to use the
 plumbing directly very often, but it can be good to know what the
-plumbing does for when the porcelain isn't flushing... 
+plumbing does for when the porcelain isn't flushing.
+
+The material presented here often goes deep describing how things
+work internally.  If you are mostly interested in using git as a
+SCM, you can skip them during your first pass.
+
+[NOTE]
+And those "too deep" descriptions are often marked as Note.
+
+[NOTE]
+If you are already familiar with another version control system,
+like CVS, you may want to take a look at
+link:everyday.html[Everyday GIT in 20 commands or so] first
+before reading this.
 
 
 Creating a git repository
@@ -36,14 +49,16 @@ To start up, create a subdirectory for it, change into that
 subdirectory, and initialize the git infrastructure with `git-init-db`:
 
 ------------------------------------------------
-mkdir git-tutorial
+$ mkdir git-tutorial
-cd git-tutorial
+$ cd git-tutorial
-git-init-db
+$ git-init-db
 ------------------------------------------------
 
 to which git will reply
 
-	defaulting to local storage area
+----------------
+defaulting to local storage area
+----------------
 
 which is just git's way of saying that you haven't been doing anything
 strange, and that it will have created a local `.git` directory setup for
@@ -114,8 +129,8 @@ in your git repository. We'll start off with a few bad examples, just to
 get a feel for how this works:
 
 ------------------------------------------------
-echo "Hello World" >hello
+$ echo "Hello World" >hello
-echo "Silly example" >example
+$ echo "Silly example" >example
 ------------------------------------------------
 
 you have now created two files in your working tree (aka 'working directory'), but to
@@ -129,7 +144,7 @@ actually check in your hard work, you will have to go through two steps:
 The first step is trivial: when you want to tell git about any changes
 to your working tree, you use the `git-update-index` program. That
 program normally just takes a list of filenames you want to update, but
-to avoid trivial mistakes, it refuses to add new entries to the cache
+to avoid trivial mistakes, it refuses to add new entries to the index
 (or remove existing ones) unless you explicitly tell it that you're
 adding a new entry with the `\--add` flag (or removing an entry with the
 `\--remove`) flag.
@@ -137,7 +152,7 @@ adding a new entry with the `\--add` flag (or removing an entry with the
 So to populate the index with the two files you just created, you can do
 
 ------------------------------------------------
-git-update-index --add hello example
+$ git-update-index --add hello example
 ------------------------------------------------
 
 and you have now told git to track those two files.
@@ -146,12 +161,17 @@ In fact, as you did that, if you now look into your object directory,
 you'll notice that git will have added two new objects to the object
 database. If you did exactly the steps above, you should now be able to do
 
-	ls .git/objects/??/*
+
+----------------
+$ ls .git/objects/??/*
+----------------
 
 and see two files:
 
-	.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 
+----------------
-	.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
+.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
+----------------
 
 which correspond with the objects with names of 557db... and f24c7..
 respectively.
@@ -159,13 +179,17 @@ respectively.
 If you want to, you can use `git-cat-file` to look at those objects, but
 you'll have to use the object name, not the filename of the object:
 
-	git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+----------------
+$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+----------------
 
 where the `-t` tells `git-cat-file` to tell you what the "type" of the
 object is. git will tell you that you have a "blob" object (ie just a
 regular file), and you can see the contents with
 
-	git-cat-file "blob" 557db03
+----------------
+$ git-cat-file "blob" 557db03
+----------------
 
 which will print out "Hello World". The object 557db03 is nothing
 more than the contents of your file `hello`.
@@ -188,7 +212,7 @@ was just to show that `git-update-index` did something magical, and
 actually saved away the contents of your files into the git object
 database.
 
-Updating the cache did something else too: it created a `.git/index`
+Updating the index did something else too: it created a `.git/index`
 file. This is the index that describes your current working tree, and
 something you should be very aware of. Again, you normally never worry
 about the index file itself, but you should be aware of the fact that
@@ -202,7 +226,7 @@ In particular, let's not even check in the two files into git yet, we'll
 start off by adding another line to `hello` first:
 
 ------------------------------------------------
-echo "It's a new day for git" >>hello
+$ echo "It's a new day for git" >>hello
 ------------------------------------------------
 
 and you can now, since you told git about the previous state of `hello`, ask
@@ -210,7 +234,7 @@ git what has changed in the tree compared to your old index, using the
 `git-diff-files` command:
 
 ------------
-git-diff-files
+$ git-diff-files
 ------------
 
 Oops. That wasn't very readable. It just spit out its own internal
@@ -222,12 +246,7 @@ To make it readable, we can tell git-diff-files to output the
 differences as a patch, using the `-p` flag:
 
 ------------
-git-diff-files -p
+$ git-diff-files -p
-------------
-
-which will spit out
-
-------------
 diff --git a/hello b/hello
 index 557db03..263414f 100644
 --- a/hello
@@ -246,6 +265,17 @@ tree. That's very useful.
 A common shorthand for `git-diff-files -p` is to just write `git
 diff`, which will do the same thing.
 
+------------
+$ git diff
+diff --git a/hello b/hello
+index 557db03..263414f 100644
+--- a/hello
++++ b/hello
+@@ -1 +1,2 @@
+ Hello World
++It's a new day for git
+------------
+
 
 Committing git state
 --------------------
@@ -264,13 +294,15 @@ filenames with their contents (and their permissions), and we're
 creating the equivalent of a git "directory" object:
 
 ------------------------------------------------
-git-write-tree
+$ git-write-tree
 ------------------------------------------------
 
 and this will just output the name of the resulting tree, in this case
 (if you have done exactly as I've described) it should be
 
-	8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+8988da15d077d4829fc51d8544c097def6644dbb
+----------------
 
 which is another incomprehensible object name. Again, if you want to,
 you can use `git-cat-file -t 8988d\...` to see that this time the object
@@ -299,14 +331,16 @@ that's exactly what `git-commit-tree` spits out, we can do this
 all with a sequence of simple shell commands:
 
 ------------------------------------------------
-tree=$(git-write-tree)
+$ tree=$(git-write-tree)
-commit=$(echo 'Initial commit' | git-commit-tree $tree)
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
-git-update-ref HEAD $(commit)
+$ git-update-ref HEAD $commit
 ------------------------------------------------
 
 which will say:
 
-	Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
+----------------
 
 just to warn you about the fact that it created a totally new commit
 that is not related to anything else. Normally you do this only *once*
@@ -349,7 +383,9 @@ didn't have anything to diff against.
 
 But now we can do
 
-	git-diff-index -p HEAD
+----------------
+$ git-diff-index -p HEAD
+----------------
 
 (where `-p` has the same meaning as it did in `git-diff-files`), and it
 will show us the same difference, but for a totally different reason. 
@@ -360,7 +396,9 @@ are obviously the same, so we get the same result.
 Again, because this is a common operation, you can also just shorthand
 it with
 
-	git diff HEAD
+----------------
+$ git diff HEAD
+----------------
 
 which ends up doing the above for you.
 
@@ -396,7 +434,7 @@ work through the index file, so the first thing we need to do is to
 update the index cache:
 
 ------------------------------------------------
-git-update-index hello
+$ git-update-index hello
 ------------------------------------------------
 
 (note how we didn't need the `\--add` flag this time, since git knew
@@ -417,7 +455,7 @@ this wasn't an initial commit any more), but you've done that once
 already, so let's just use the helpful script this time:
 
 ------------------------------------------------
-git commit
+$ git commit
 ------------------------------------------------
 
 which starts an editor for you to write the commit message and tells you
@@ -426,7 +464,7 @@ a bit about what you have done.
 Write whatever message you want, and all the lines that start with '#'
 will be pruned out, and the rest will be used as the commit message for
 the change. If you decide you don't want to commit anything after all at
-this point (you can continue to edit things and update the cache), you
+this point (you can continue to edit things and update the index), you
 can just leave an empty message. Otherwise `git commit` will commit
 the change for you.
 
@@ -450,7 +488,9 @@ give it just a single commit object, and it will figure out the parent
 of that commit itself, and show the difference directly. Thus, to get
 the same diff that we've already seen several times, we can now do
 
-	git-diff-tree -p HEAD
+----------------
+$ git-diff-tree -p HEAD
+----------------
 
 (again, `-p` means to show the difference as a human-readable patch),
 and it will show what the last commit (in `HEAD`) actually changed.
@@ -505,13 +545,17 @@ activities.
 To see the whole history of our pitiful little git-tutorial project, you
 can do
 
-	git log
+----------------
+$ git log
+----------------
 
 which shows just the log messages, or if we want to see the log together
 with the associated patches use the more complex (and much more
 powerful)
 
-	git-whatchanged -p --root
+----------------
+$ git-whatchanged -p --root
+----------------
 
 and you will see exactly what has changed in the repository over its
 short history. 
@@ -547,14 +591,16 @@ it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
 So the simplest form of tag involves nothing more than
 
 ------------------------------------------------
-git tag my-first-tag
+$ git tag my-first-tag
 ------------------------------------------------
 
 which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
 file, after which point you can then use this symbolic name for that
 particular state. You can, for example, do
 
-	git diff my-first-tag
+----------------
+$ git diff my-first-tag
+----------------
 
 to diff your current state against that tag (which at this point will
 obviously be an empty diff, but if you continue to develop and commit
@@ -568,7 +614,9 @@ you really did
 that tag. You create these annotated tags with either the `-a` or
 `-s` flag to `git tag`:
 
-	git tag -s <tagname>
+----------------
+$ git tag -s <tagname>
+----------------
 
 which will sign the current `HEAD` (but you can also give it another
 argument that specifies the thing to tag, ie you could have tagged the
@@ -584,8 +632,8 @@ name for the state at that point.
 Copying repositories
 --------------------
 
-git repositories are normally totally self-sufficient, and it's worth noting
+git repositories are normally totally self-sufficient and relocatable
-that unlike CVS, for example, there is no separate notion of
+Unlike CVS, for example, there is no separate notion of
 "repository" and "working tree". A git repository normally *is* the
 working tree, with the local git information hidden in the `.git`
 subdirectory. There is nothing else. What you see is what you got.
@@ -602,8 +650,10 @@ This has two implications:
 
  - if you grow bored with the tutorial repository you created (or you've
    made a mistake and want to start all over), you can just do simple
-
++
-	rm -rf git-tutorial
+----------------
+$ rm -rf git-tutorial
+----------------
 +
 and it will be gone. There's no external repository, and there's no
 history outside the project you created.
@@ -618,8 +668,10 @@ Note that when you've moved or copied a git repository, your git index
 file (which caches various information, notably some of the "stat"
 information for the files involved) will likely need to be refreshed.
 So after you do a `cp -a` to create a new copy, you'll want to do
-
++
-	git-update-index --refresh
+----------------
+$ git-update-index --refresh
+----------------
 +
 in the new repository to make sure that the index file is up-to-date.
 
@@ -633,8 +685,10 @@ repositories you often want to make sure that the index cache is in some
 known state (you don't know *what* they've done and not yet checked in),
 so usually you'll precede the `git-update-index` with a
 
-	git-read-tree --reset HEAD
+----------------
-	git-update-index --refresh
+$ git-read-tree --reset HEAD
+$ git-update-index --refresh
+----------------
 
 which will force a total index re-build from the tree pointed to by `HEAD`.
 It resets the index contents to `HEAD`, and then the `git-update-index`
@@ -645,7 +699,9 @@ tells you they need to be updated.
 
 The above can also be written as simply
 
-	git reset
+----------------
+$ git reset
+----------------
 
 and in fact a lot of the common git command combinations can be scripted
 with the `git xyz` interfaces.  You can learn things by just looking
@@ -665,20 +721,26 @@ first create your own subdirectory for the project, and then copy the
 raw repository contents into the `.git` directory. For example, to
 create your own copy of the git repository, you'd do the following
 
-	mkdir my-git
+----------------
-	cd my-git
+$ mkdir my-git
-	rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
+$ cd my-git
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
+----------------
 
 followed by 
 
-	git-read-tree HEAD
+----------------
+$ git-read-tree HEAD
+----------------
 
 to populate the index. However, now you have populated the index, and
 you have all the git internal files, but you will notice that you don't
 actually have any of the working tree files to work on. To get
 those, you'd check them out with
 
-	git-checkout-index -u -a
+----------------
+$ git-checkout-index -u -a
+----------------
 
 where the `-u` flag means that you want the checkout to keep the index
 up-to-date (so that you don't have to refresh it afterward), and the
@@ -689,9 +751,11 @@ files).
 
 Again, this can all be simplified with
 
-	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
+----------------
-	cd my-git
+$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
-	git checkout
+$ cd my-git
+$ git checkout
+----------------
 
 which will end up doing all of the above for you.
 
@@ -719,7 +783,7 @@ used earlier, and create a branch in it. You do that by simply just
 saying that you want to check out a new branch:
 
 ------------
-git checkout -b mybranch
+$ git checkout -b mybranch
 ------------
 
 will create a new branch based at the current `HEAD` position, and switch
@@ -733,7 +797,7 @@ just telling `git checkout` what the base of the checkout would be.
 In other words, if you have an earlier tag or branch, you'd just do
 
 ------------
-git checkout -b mybranch earlier-commit
+$ git checkout -b mybranch earlier-commit
 ------------
 
 and it would create the new branch `mybranch` at the earlier commit,
@@ -743,27 +807,27 @@ and check out the state at that time.
 You can always just jump back to your original `master` branch by doing
 
 ------------
-git checkout master
+$ git checkout master
 ------------
 
 (or any other branch-name, for that matter) and if you forget which
 branch you happen to be on, a simple
 
 ------------
-ls -l .git/HEAD
+$ ls -l .git/HEAD
 ------------
 
 will tell you where it's pointing (Note that on platforms with bad or no
 symlink support, you have to execute
 
 ------------
-cat .git/HEAD
+$ cat .git/HEAD
 ------------
 
 instead). To get the list of branches you have, you can say
 
 ------------
-git branch
+$ git branch
 ------------
 
 which is nothing more than a simple script around `ls .git/refs/heads`.
@@ -773,7 +837,7 @@ Sometimes you may wish to create a new branch _without_ actually
 checking it out and switching to it. If so, just use the command
 
 ------------
-git branch <branchname> [startingpoint]
+$ git branch <branchname> [startingpoint]
 ------------
 
 which will simply _create_ the branch, but will not do anything further. 
@@ -792,9 +856,9 @@ being the same as the original `master` branch, let's make sure we're in
 that branch, and do some work there.
 
 ------------------------------------------------
-git checkout mybranch
+$ git checkout mybranch
-echo "Work, work, work" >>hello
+$ echo "Work, work, work" >>hello
-git commit -m 'Some work.' hello
+$ git commit -m 'Some work.' hello
 ------------------------------------------------
 
 Here, we just added another line to `hello`, and we used a shorthand for
@@ -807,7 +871,7 @@ does some work in the original branch, and simulate that by going back
 to the master branch, and editing the same file differently there:
 
 ------------
-git checkout master
+$ git checkout master
 ------------
 
 Here, take a moment to look at the contents of `hello`, and notice how they
@@ -815,9 +879,9 @@ don't contain the work we just did in `mybranch` -- because that work
 hasn't happened in the `master` branch at all. Then do
 
 ------------
-echo "Play, play, play" >>hello
+$ echo "Play, play, play" >>hello
-echo "Lots of fun" >>example
+$ echo "Lots of fun" >>example
-git commit -m 'Some fun.' hello example
+$ git commit -m 'Some fun.' hello example
 ------------
 
 since the master branch is obviously in a much better mood.
@@ -826,7 +890,9 @@ Now, you've got two branches, and you decide that you want to merge the
 work done. Before we do that, let's introduce a cool graphical tool that
 helps you view what's going on:
 
-	gitk --all
+----------------
+$ gitk --all
+----------------
 
 will show you graphically both of your branches (that's what the `\--all`
 means: normally it will just show you your current `HEAD`) and their
@@ -836,14 +902,14 @@ source.
 Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
 to merge the work we did on the `mybranch` branch into the `master`
 branch (which is currently our `HEAD` too). To do that, there's a nice
-script called `git resolve`, which wants to know which branches you want
+script called `git merge`, which wants to know which branches you want
 to resolve and what the merge is all about:
 
 ------------
-git resolve HEAD mybranch "Merge work in mybranch"
+$ git merge "Merge work in mybranch" HEAD mybranch
 ------------
 
-where the third argument is going to be used as the commit message if
+where the first argument is going to be used as the commit message if
 the merge can be resolved automatically.
 
 Now, in this case we've intentionally created a situation where the
@@ -851,12 +917,15 @@ merge will need to be fixed up by hand, though, so git will do as much
 of it as it can automatically (which in this case is just merge the `example`
 file, which had no differences in the `mybranch` branch), and say:
 
-	Simple merge failed, trying Automatic merge
+----------------
-	Auto-merging hello.
+	Trying really trivial in-index merge...
-	merge: warning: conflicts during merge
+	fatal: Merge requires file-level merging
-	ERROR: Merge conflict in hello.
+	Nope.
-	fatal: merge program failed
+	...
-	Automatic merge failed, fix up by hand
+	Auto-merging hello 
+	CONFLICT (content): Merge conflict in hello 
+	Automatic merge failed/prevented; fix up by hand
+----------------
 
 which is way too verbose, but it basically tells you that it failed the
 really trivial merge ("Simple merge") and did an "Automatic merge"
@@ -877,7 +946,7 @@ Work, work, work
 and once you're happy with your manual merge, just do a
 
 ------------
-git commit hello
+$ git commit hello
 ------------
 
 which will very loudly warn you that you're now committing a merge
@@ -896,10 +965,10 @@ environment, is `git show-branch`.
 
 ------------------------------------------------
 $ git show-branch master mybranch
-* [master] Merged "mybranch" changes.
+* [master] Merge work in mybranch
  ! [mybranch] Some work.
 --
-+  [master] Merged "mybranch" changes.
++  [master] Merge work in mybranch
 ++ [mybranch] Some work.
 ------------------------------------------------
 
@@ -927,17 +996,19 @@ to the `master` branch. Let's go back to `mybranch`, and run
 resolve to get the "upstream changes" back to your branch.
 
 ------------
-git checkout mybranch
+$ git checkout mybranch
-git resolve HEAD master "Merge upstream changes."
+$ git merge "Merge upstream changes." HEAD master
 ------------
 
 This outputs something like this (the actual commit object names
 would be different)
 
-	Updating from ae3a2da... to a80b4aa....
+----------------
-	 example |    1 +
+Updating from ae3a2da... to a80b4aa....
-	 hello   |    1 +
+ example |    1 +
-	 2 files changed, 2 insertions(+), 0 deletions(-)
+ hello   |    1 +
+ 2 files changed, 2 insertions(+), 0 deletions(-)
+----------------
 
 Because your branch did not contain anything more than what are
 already merged into the `master` branch, the resolve operation did
@@ -950,10 +1021,10 @@ looks like, or run `show-branch`, which tells you this.
 
 ------------------------------------------------
 $ git show-branch master mybranch
-! [master] Merged "mybranch" changes.
+! [master] Merge work in mybranch
- * [mybranch] Merged "mybranch" changes.
+ * [mybranch] Merge work in mybranch
 --
-++ [master] Merged "mybranch" changes.
+++ [master] Merge work in mybranch
 ------------------------------------------------
 
 
@@ -963,14 +1034,16 @@ Merging external work
 It's usually much more common that you merge with somebody else than
 merging with your own branches, so it's worth pointing out that git
 makes that very easy too, and in fact, it's not that different from
-doing a `git resolve`. In fact, a remote merge ends up being nothing
+doing a `git merge`. In fact, a remote merge ends up being nothing
 more than "fetch the work from a remote repository into a temporary tag"
-followed by a `git resolve`.
+followed by a `git merge`.
 
 Fetching from a remote repository is done by, unsurprisingly,
 `git fetch`:
 
-	git fetch <remote-repository>
+----------------
+$ git fetch <remote-repository>
+----------------
 
 One of the following transports can be used to name the
 repository to download from:
@@ -1015,12 +1088,13 @@ This transport was designed for anonymous downloading.  Like SSH
 transport, it finds out the set of objects the downstream side
 lacks and transfers (close to) minimum set of objects.
 
-HTTP(s)::
+HTTP(S)::
 	`http://remote.machine/path/to/repo.git/`
 +
-HTTP and HTTPS transport are used only for downloading.  They
+Downloader from http and https URL
-first obtain the topmost commit object name from the remote site
+first obtains the topmost commit object name from the remote site
-by looking at `repo.git/info/refs` file, tries to obtain the
+by looking at the specified refname under `repo.git/refs/` directory,
+and then tries to obtain the
 commit object by downloading from `repo.git/objects/xx/xxx\...`
 using the object name of that commit object.  Then it reads the
 commit object to find out its parent commits and the associate
@@ -1031,7 +1105,9 @@ sometimes also called 'commit walkers'.
 The 'commit walkers' are sometimes also called 'dumb
 transports', because they do not require any git aware smart
 server like git Native transport does.  Any stock HTTP server
-would suffice.
+that does not even support directory index would suffice.  But
+you must prepare your repository with `git-update-server-info`
+to help dumb transport downloaders.
 +
 There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
 programs, which are 'commit walkers'; they outlived their
@@ -1045,7 +1121,9 @@ However -- it's such a common thing to `fetch` and then
 immediately `resolve`, that it's called `git pull`, and you can
 simply do
 
-	git pull <remote-repository>
+----------------
+$ git pull <remote-repository>
+----------------
 
 and optionally give a branch-name for the remote end as a second
 argument.
@@ -1073,8 +1151,8 @@ the remote repository URL in a file under .git/remotes/
 directory, like this:
 
 ------------------------------------------------
-mkdir -p .git/remotes/
+$ mkdir -p .git/remotes/
-cat >.git/remotes/linus <<\EOF
+$ cat >.git/remotes/linus <<\EOF
 URL: http://www.kernel.org/pub/scm/git/git.git/
 EOF
 ------------------------------------------------
@@ -1084,7 +1162,7 @@ The URL specified in such file can even be a prefix
 of a full URL, like this:
 
 ------------------------------------------------
-cat >.git/remotes/jgarzik <<\EOF
+$ cat >.git/remotes/jgarzik <<\EOF
 URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
 EOF
 ------------------------------------------------
@@ -1103,6 +1181,157 @@ the above are equivalent to:
 . `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
 
 
+How does the merge work?
+------------------------
+
+We said this tutorial shows what plumbing does to help you cope
+with the porcelain that isn't flushing, but we so far did not
+talk about how the merge really works.  If you are following
+this tutorial the first time, I'd suggest to skip to "Publishing
+your work" section and come back here later.
+
+OK, still with me?  To give us an example to look at, let's go
+back to the earlier repository with "hello" and "example" file,
+and bring ourselves back to the pre-merge state:
+
+------------
+$ git show-branch --more=3 master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+++ [master] Merge work in mybranch
+++ [master^2] Some work.
+++ [master^] Some fun.
+------------
+
+Remember, before running `git merge`, our `master` head was at
+"Some fun." commit, while our `mybranch` head was at "Some
+work." commit.
+
+------------
+$ git checkout mybranch
+$ git reset --hard master^2
+$ git checkout master
+$ git reset --hard master^
+------------
+
+After rewinding, the commit structure should look like this:
+
+------------
+$ git show-branch
+* [master] Some fun.
+ ! [mybranch] Some work.
+--
+ + [mybranch] Some work.
++  [master] Some fun.
+++ [mybranch^] New day.
+------------
+
+Now we are ready to experiment with the merge by hand.
+
+`git merge` command, when merging two branches, uses 3-way merge
+algorithm.  First, it finds the common ancestor between them.
+The command it uses is `git-merge-base`:
+
+------------
+$ mb=$(git-merge-base HEAD mybranch)
+------------
+
+The command writes the commit object name of the common ancestor
+to the standard output, so we captured its output to a variable,
+because we will be using it in the next step.  BTW, the common
+ancestor commit is the "New day." commit in this case.  You can
+tell it by:
+
+------------
+$ git-name-rev $mb
+my-first-tag
+------------
+
+After finding out a common ancestor commit, the second step is
+this:
+
+------------
+$ git-read-tree -m -u $mb HEAD mybranch
+------------
+
+This is the same `git-read-tree` command we have already seen,
+but it takes three trees, unlike previous examples.  This reads
+the contents of each tree into different 'stage' in the index
+file (the first tree goes to stage 1, the second stage 2,
+etc.).  After reading three trees into three stages, the paths
+that are the same in all three stages are 'collapsed' into stage
+0.  Also paths that are the same in two of three stages are
+collapsed into stage 0, taking the SHA1 from either stage 2 or
+stage 3, whichever is different from stage 1 (i.e. only one side
+changed from the common ancestor).
+
+After 'collapsing' operation, paths that are different in three
+trees are left in non-zero stages.  At this point, you can
+inspect the index file with this command:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1	hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2	hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
+------------
+
+In our example of only two files, we did not have unchanged
+files so only 'example' resulted in collapsing, but in real-life
+large projects, only small number of files change in one commit,
+and this 'collapsing' tends to trivially merge most of the paths
+fairly quickly, leaving only a handful the real changes in non-zero
+stages.
+
+To look at only non-zero stages, use `\--unmerged` flag:
+
+------------
+$ git-ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1	hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2	hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
+------------
+
+The next step of merging is to merge these three versions of the
+file, using 3-way merge.  This is done by giving
+`git-merge-one-file` command as one of the arguments to
+`git-merge-index` command:
+
+------------
+$ git-merge-index git-merge-one-file hello
+Auto-merging hello.
+merge: warning: conflicts during merge
+ERROR: Merge conflict in hello.
+fatal: merge program failed
+------------
+
+`git-merge-one-file` script is called with parameters to
+describe those three versions, and is responsible to leave the
+merge results in the working tree.
+It is a fairly straightforward shell script, and
+eventually calls `merge` program from RCS suite to perform a
+file-level 3-way merge.  In this case, `merge` detects
+conflicts, and the merge result with conflict marks is left in
+the working tree..  This can be seen if you run `ls-files
+--stage` again at this point:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1	hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2	hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
+------------
+
+This is the state of the index file and the working file after
+`git merge` returns control back to you, leaving the conflicting
+merge for you to resolve.  Notice that the path `hello` is still
+unmerged, and what you see with `git diff` at this point is
+differences since stage 2 (i.e. your version).
+
+
 Publishing your work
 --------------------
 
@@ -1148,7 +1377,7 @@ project `my-git`. After logging into the remote machine, create
 an empty directory:
 
 ------------
-mkdir my-git.git
+$ mkdir my-git.git
 ------------
 
 Then, make that directory into a git repository by running
@@ -1156,7 +1385,7 @@ Then, make that directory into a git repository by running
 `.git`, we do things slightly differently:
 
 ------------
-GIT_DIR=my-git.git git-init-db
+$ GIT_DIR=my-git.git git-init-db
 ------------
 
 Make sure this directory is available for others you want your
@@ -1182,7 +1411,7 @@ Come back to the machine you have your private repository. From
 there, run this command:
 
 ------------
-git push <public-host>:/path/to/my-git.git master
+$ git push <public-host>:/path/to/my-git.git master
 ------------
 
 This synchronizes your public repository to match the named
@@ -1194,7 +1423,7 @@ repository. Kernel.org mirror network takes care of the
 propagation to other publicly visible machines:
 
 ------------
-git push master.kernel.org:/pub/scm/git/git.git/ 
+$ git push master.kernel.org:/pub/scm/git/git.git/ 
 ------------
 
 
@@ -1209,7 +1438,7 @@ immutable once they are created, there is a way to optimize the
 storage by "packing them together". The command
 
 ------------
-git repack
+$ git repack
 ------------
 
 will do it for you. If you followed the tutorial examples, you
@@ -1235,7 +1464,7 @@ Once you have packed objects, you do not need to leave the
 unpacked objects that are contained in the pack file anymore.
 
 ------------
-git prune-packed
+$ git prune-packed
 ------------
 
 would remove them for you.
@@ -1291,12 +1520,13 @@ A recommended workflow for a "project lead" goes like this:
 2. Prepare a public repository accessible to others.
 +
 If other people are pulling from your repository over dumb
-transport protocols, you need to keep this repository 'dumb
+transport protocols (HTTP), you need to keep this repository
-transport friendly'.  After `git init-db`,
+'dumb transport friendly'.  After `git init-db`,
 `$GIT_DIR/hooks/post-update` copied from the standard templates
 would contain a call to `git-update-server-info` but the
 `post-update` hook itself is disabled by default -- enable it
-with `chmod +x post-update`.
+with `chmod +x post-update`.  This makes sure `git-update-server-info`
+keeps the necessary files up-to-date.
 
 3. Push into the public repository from your primary
    repository.
@@ -1332,7 +1562,10 @@ on that project and has an own "public repository" goes like this:
    the "project lead" person does.
 
 3. Copy over the packed files from "project lead" public
-   repository to your public repository.
+   repository to your public repository, unless the "project
+   lead" repository lives on the same machine as yours.  In the
+   latter case, you can use `objects/info/alternates` file to
+   point at the repository you are borrowing from.
 
 4. Push into the public repository from your primary
    repository. Run `git repack`, and possibly `git prune` if the
@@ -1392,7 +1625,9 @@ cooperation you are probably more familiar with as well.
 For this, set up a public repository on a machine that is
 reachable via SSH by people with "commit privileges".  Put the
 committers in the same user group and make the repository
-writable by that group.
+writable by that group.  Make sure their umasks are set up to
+allow group members to write into directories other members
+have created.
 
 You, as an individual committer, then:
 
@@ -1432,14 +1667,49 @@ fast forward.  You need to pull and merge those other changes
 back before you push your work when it happens.
 
 
+Advanced Shared Repository Management
+-------------------------------------
+
+Being able to push into a shared repository means being able to
+write into it.  If your developers are coming over the network,
+this means you, as the repository administrator, need to give
+each of them an SSH access to the shared repository machine.
+
+In some cases, though, you may not want to give a normal shell
+account to them, but want to restrict them to be able to only
+do `git push` into the repository and nothing else.
+
+You can achieve this by setting the login shell of your
+developers on the shared repository host to `git-shell` program.
+
+[NOTE]
+Most likely you would also need to list `git-shell` program in
+`/etc/shells` file.
+
+This restricts the set of commands that can be run from incoming
+SSH connection for these users to only `receive-pack` and
+`upload-pack`, so the only thing they can do are `git fetch` and
+`git push`.
+
+You still need to create UNIX user accounts for each developer,
+and put them in the same group.  Make sure that the repository
+shared among these developers is writable by that group.
+
+You can implement finer grained branch policies using update
+hooks.  There is a document ("control access to branches") in
+Documentation/howto by Carl Baldwin and JC outlining how to (1)
+limit access to branch per user, (2) forbid overwriting existing
+tags.
+
+
 Bundling your work together
 ---------------------------
 
 It is likely that you will be working on more than one thing at
-a time.  It is easy to use those more-or-less independent tasks
+a time.  It is easy to manage those more-or-less independent tasks
 using branches with git.
 
-We have already seen how branches work in a previous example,
+We have already seen how branches work previously,
 with "fun and work" example using two branches.  The idea is the
 same if there are more than two branches.  Let's say you started
 out from "master" head, and have some new code in the "master"
@@ -1464,8 +1734,8 @@ in both of them.  You could merge in 'diff-fix' first and then
 'commit-fix' next, like this:
 
 ------------
-$ git resolve master diff-fix 'Merge fix in diff-fix'
+$ git merge 'Merge fix in diff-fix' master diff-fix
-$ git resolve master commit-fix 'Merge fix in commit-fix'
+$ git merge 'Merge fix in commit-fix' master commit-fix
 ------------
 
 Which would result in:
@@ -1498,8 +1768,8 @@ $ git reset --hard master~2
 ------------
 
 You can make sure 'git show-branch' matches the state before
-those two 'git resolve' you just did.  Then, instead of running
+those two 'git merge' you just did.  Then, instead of running
-two 'git resolve' commands in a row, you would pull these two
+two 'git merge' commands in a row, you would pull these two
 branch heads (this is known as 'making an Octopus'):
 
 ------------

INSTALL

@@ -5,10 +5,13 @@ Normally you can just do "make" followed by "make install", and that
 will install the git programs in your own ~/bin/ directory.  If you want
 to do a global install, you can do
 
-	make prefix=/usr install
+	$ make prefix=/usr ;# as yourself
+	# make prefix=/usr install ;# as root
 
-(or prefix=/usr/local, of course).  Some day somebody may send me a RPM
+(or prefix=/usr/local, of course).  Just like any program suite
-spec file or something, and you can do "make rpm" or whatever.
+that uses $prefix, the built results have some paths encoded,
+which are derived from $prefix, so "make all; make prefix=/usr
+install" would not work.
 
 Issues of note:
 
@@ -46,6 +49,9 @@ Issues of note:
 	  transfer, you are probabaly OK if you do not have
 	  them.
 
+	- expat library; git-http-push uses it for remote lock
+	  management over DAV.  Similar to "curl" above, this is optional.
+
 	- "GNU diff" to generate patches.  Of course, you don't _have_ to
 	  generate patches if you don't want to, but let's face it, you'll
 	  be wanting to. Or why did you get git in the first place?
@@ -69,3 +75,18 @@ Issues of note:
           history graphically
 
 	- "ssh" is used to push and pull over the net
+
+	- "perl" and POSIX-compliant shells are needed to use most of
+	  the barebone Porcelainish scripts.
+
+	- "python" 2.3 or more recent; if you have 2.3, you may need
+          to build with "make WITH_OWN_SUBPROCESS_PY=YesPlease".
+
+ - Some platform specific issues are dealt with Makefile rules,
+   but depending on your specific installation, you may not
+   have all the libraries/tools needed, or you may have
+   necessary libraries at unusual locations.  Please look at the
+   top of the Makefile to see what can be adjusted for your needs.
+   You can place local settings in config.mak and the Makefile
+   will include them.  Note that config.mak is not distributed;
+   the name is reserved for local settings.

Makefile

@@ -1,3 +1,6 @@
+# The default target of this Makefile is...
+all:
+
 # Define MOZILLA_SHA1 environment variable when running make to make use of
 # a bundled SHA1 routine coming from Mozilla. It is GPL'd and should be fast
 # on non-x86 architectures (e.g. PowerPC), while the OpenSSL version (default
@@ -6,14 +9,20 @@
 # Define NO_OPENSSL environment variable if you do not have OpenSSL. You will
 # miss out git-rev-list --merge-order. This also implies MOZILLA_SHA1.
 #
-# Define NO_CURL if you do not have curl installed.  git-http-pull is not
+# Define NO_CURL if you do not have curl installed.  git-http-pull and
-# built, and you cannot use http:// and https:// transports.
+# git-http-push are not built, and you cannot use http:// and https://
+# transports.
 #
 # Define CURLDIR=/foo/bar if your curl header and library files are in
 # /foo/bar/include and /foo/bar/lib directories.
 #
+# Define NO_EXPAT if you do not have expat installed.  git-http-push is
+# not built, and you cannot push using http:// and https:// transports.
+#
 # Define NO_STRCASESTR if you don't have strcasestr.
 #
+# Define NO_SETENV if you don't have setenv in the C library.
+#
 # Define PPC_SHA1 environment variable when running make to make use of
 # a bundled SHA1 routine optimized for PowerPC.
 #
@@ -37,25 +46,23 @@
 # 1461501637330902918203684832716283019655932542976 hashes do not give you
 # sufficient guarantee that no collisions between objects will ever happen.
 
-# DEFINES += -DCOLLISION_CHECK
-
 # Define USE_NSEC below if you want git to care about sub-second file mtimes
 # and ctimes. Note that you need recent glibc (at least 2.2.4) for this, and
 # it will BREAK YOUR LOCAL DIFFS! show-diff and anything using it will likely
 # randomly break unless your underlying filesystem supports those sub-second
 # times (my ext3 doesn't).
 
-# DEFINES += -DUSE_NSEC
-
 # Define USE_STDEV below if you want git to care about the underlying device
 # change being considered an inode change from the update-cache perspective.
 
-# DEFINES += -DUSE_STDEV
+GIT_VERSION = 1.0.8
 
-GIT_VERSION = 0.99.9d
+# CFLAGS and LDFLAGS are for the users to override from the command line.
 
 CFLAGS = -g -O2 -Wall
-ALL_CFLAGS = $(CFLAGS) $(PLATFORM_DEFINES) $(DEFINES)
+LDFLAGS =
+ALL_CFLAGS = $(CFLAGS)
+ALL_LDFLAGS = $(LDFLAGS)
 
 prefix = $(HOME)
 bindir = $(prefix)/bin
@@ -82,27 +89,33 @@ SCRIPT_SH = \
 	git-cherry.sh git-clone.sh git-commit.sh \
 	git-count-objects.sh git-diff.sh git-fetch.sh \
 	git-format-patch.sh git-log.sh git-ls-remote.sh \
-	git-merge-one-file.sh git-octopus.sh git-parse-remote.sh \
+	git-merge-one-file.sh git-parse-remote.sh \
 	git-prune.sh git-pull.sh git-push.sh git-rebase.sh \
 	git-repack.sh git-request-pull.sh git-reset.sh \
 	git-resolve.sh git-revert.sh git-sh-setup.sh git-status.sh \
-	git-tag.sh git-verify-tag.sh git-whatchanged.sh git.sh \
+	git-tag.sh git-verify-tag.sh git-whatchanged.sh \
 	git-applymbox.sh git-applypatch.sh git-am.sh \
 	git-merge.sh git-merge-stupid.sh git-merge-octopus.sh \
-	git-merge-resolve.sh git-merge-ours.sh git-grep.sh
+	git-merge-resolve.sh git-merge-ours.sh git-grep.sh \
+	git-lost-found.sh
 
 SCRIPT_PERL = \
 	git-archimport.perl git-cvsimport.perl git-relink.perl \
-	git-rename.perl git-shortlog.perl git-fmt-merge-msg.perl \
+	git-shortlog.perl git-fmt-merge-msg.perl \
-	git-svnimport.perl git-mv.perl
+	git-svnimport.perl git-mv.perl git-cvsexportcommit.perl
 
 SCRIPT_PYTHON = \
 	git-merge-recursive.py
 
+SCRIPTS = $(patsubst %.sh,%,$(SCRIPT_SH)) \
+	  $(patsubst %.perl,%,$(SCRIPT_PERL)) \
+	  $(patsubst %.py,%,$(SCRIPT_PYTHON)) \
+	  gitk git-cherry-pick
+
 # The ones that do not have to link with lcrypto nor lz.
 SIMPLE_PROGRAMS = \
 	git-get-tar-commit-id$X git-mailinfo$X git-mailsplit$X \
-	git-stripspace$X git-var$X git-daemon$X
+	git-stripspace$X git-daemon$X
 
 # ... and all the rest
 PROGRAMS = \
@@ -122,32 +135,34 @@ PROGRAMS = \
 	git-unpack-objects$X git-update-index$X git-update-server-info$X \
 	git-upload-pack$X git-verify-pack$X git-write-tree$X \
 	git-update-ref$X git-symbolic-ref$X git-check-ref-format$X \
-	git-name-rev$X $(SIMPLE_PROGRAMS)
+	git-name-rev$X git-pack-redundant$X git-repo-config$X git-var$X
+
+# what 'all' will build and 'install' will install.
+ALL_PROGRAMS = $(PROGRAMS) $(SIMPLE_PROGRAMS) $(SCRIPTS) git$X
 
 # Backward compatibility -- to be removed after 1.0
 PROGRAMS += git-ssh-pull$X git-ssh-push$X
 
-GIT_LIST_TWEAK =
+# Set paths to tools early so that they can be used for version tests.
+ifndef SHELL_PATH
+	SHELL_PATH = /bin/sh
+endif
+ifndef PERL_PATH
+	PERL_PATH = /usr/bin/perl
+endif
+ifndef PYTHON_PATH
+	PYTHON_PATH = /usr/bin/python
+endif
 
 PYMODULES = \
 	gitMergeCommon.py
 
-ifdef WITH_OWN_SUBPROCESS_PY
-	PYMODULES += compat/subprocess.py
-endif
-
-ifdef WITH_SEND_EMAIL
-	SCRIPT_PERL += git-send-email.perl
-else
-	GIT_LIST_TWEAK += -e '/^send-email$$/d'
-endif
-
 LIB_FILE=libgit.a
 
 LIB_H = \
 	blob.h cache.h commit.h count-delta.h csum-file.h delta.h \
 	diff.h epoch.h object.h pack.h pkt-line.h quote.h refs.h \
-	run-command.h strbuf.h tag.h tree.h
+	run-command.h strbuf.h tag.h tree.h git-compat-util.h
 
 DIFF_OBJS = \
 	diff.o diffcore-break.o diffcore-order.o diffcore-pathspec.o \
@@ -160,6 +175,7 @@ LIB_OBJS = \
 	quote.o read-cache.o refs.o run-command.o \
 	server-info.o setup.o sha1_file.o sha1_name.o strbuf.o \
 	tag.o tree.o usage.o config.o environment.o ctype.o copy.o \
+	fetch-clone.o \
 	$(DIFF_OBJS)
 
 LIBS = $(LIB_FILE)
@@ -181,10 +197,17 @@ shellquote = '$(call shq,$(1))'
 uname_S := $(shell sh -c 'uname -s 2>/dev/null || echo not')
 uname_M := $(shell sh -c 'uname -m 2>/dev/null || echo not')
 uname_O := $(shell sh -c 'uname -o 2>/dev/null || echo not')
+uname_R := $(shell sh -c 'uname -r 2>/dev/null || echo not')
 
 ifeq ($(uname_S),Darwin)
 	NEEDS_SSL_WITH_CRYPTO = YesPlease
 	NEEDS_LIBICONV = YesPlease
+	## fink
+	ALL_CFLAGS += -I/sw/include
+	ALL_LDFLAGS += -L/sw/lib
+	## darwinports
+	ALL_CFLAGS += -I/opt/local/include
+	ALL_LDFLAGS += -L/opt/local/lib
 endif
 ifeq ($(uname_S),SunOS)
 	NEEDS_SOCKET = YesPlease
@@ -192,21 +215,38 @@ ifeq ($(uname_S),SunOS)
 	NEEDS_LIBICONV = YesPlease
 	SHELL_PATH = /bin/bash
 	NO_STRCASESTR = YesPlease
+	ifeq ($(uname_R),5.8)
+		NO_SETENV = YesPlease
+	endif
 	INSTALL = ginstall
 	TAR = gtar
-	PLATFORM_DEFINES += -D__EXTENSIONS__
+	ALL_CFLAGS += -D__EXTENSIONS__
 endif
 ifeq ($(uname_O),Cygwin)
 	NO_STRCASESTR = YesPlease
 	NEEDS_LIBICONV = YesPlease
+	# There are conflicting reports about this.
+	# On some boxes NO_MMAP is needed, and not so elsewhere.
+	# Try uncommenting this if you see things break -- YMMV.
+	# NO_MMAP = YesPlease
 	NO_IPV6 = YesPlease
 	X = .exe
-	PLATFORM_DEFINES += -DUSE_SYMLINK_HEAD=0
+	ALL_CFLAGS += -DUSE_SYMLINK_HEAD=0
 endif
 ifeq ($(uname_S),OpenBSD)
 	NO_STRCASESTR = YesPlease
 	NEEDS_LIBICONV = YesPlease
-	PLATFORM_DEFINES += -I/usr/local/include -L/usr/local/lib
+	ALL_CFLAGS += -I/usr/local/include
+	ALL_LDFLAGS += -L/usr/local/lib
+endif
+ifeq ($(uname_S),NetBSD)
+	NEEDS_LIBICONV = YesPlease
+	ALL_CFLAGS += -I/usr/pkg/include
+	ALL_LDFLAGS += -L/usr/pkg/lib -Wl,-rpath,/usr/pkg/lib
+endif
+ifeq ($(uname_S),AIX)
+	NO_STRCASESTR=YesPlease
+	NEEDS_LIBICONV=YesPlease
 endif
 ifneq (,$(findstring arm,$(uname_M)))
 	ARM_SHA1 = YesPlease
@@ -214,25 +254,34 @@ endif
 
 -include config.mak
 
+ifdef WITH_OWN_SUBPROCESS_PY
+	PYMODULES += compat/subprocess.py
+else
+	ifneq ($(shell $(PYTHON_PATH) -c 'import subprocess;print"OK"' 2>/dev/null),OK)
+		PYMODULES += compat/subprocess.py
+	endif
+endif
+
+ifdef WITH_SEND_EMAIL
+	SCRIPT_PERL += git-send-email.perl
+endif
+
 ifndef NO_CURL
 	ifdef CURLDIR
-		# This is still problematic -- gcc does not want -R.
+		# This is still problematic -- gcc does not always want -R.
-		CFLAGS += -I$(CURLDIR)/include
+		ALL_CFLAGS += -I$(CURLDIR)/include
 		CURL_LIBCURL = -L$(CURLDIR)/lib -R$(CURLDIR)/lib -lcurl
 	else
 		CURL_LIBCURL = -lcurl
 	endif
 	PROGRAMS += git-http-fetch$X
-endif
+	curl_check := $(shell (echo 070908; curl-config --vernum) | sort -r | sed -ne 2p)
-
+	ifeq "$(curl_check)" "070908"
-ifndef SHELL_PATH
+		ifndef NO_EXPAT
-	SHELL_PATH = /bin/sh
+			EXPAT_LIBEXPAT = -lexpat
-endif
+			PROGRAMS += git-http-push$X
-ifndef PERL_PATH
+		endif
-	PERL_PATH = /usr/bin/perl
+	endif
-endif
-ifndef PYTHON_PATH
-	PYTHON_PATH = /usr/bin/python
 endif
 
 ifndef NO_OPENSSL
@@ -240,13 +289,13 @@ ifndef NO_OPENSSL
 	OPENSSL_LIBSSL = -lssl
 	ifdef OPENSSLDIR
 		# Again this may be problematic -- gcc does not always want -R.
-		CFLAGS += -I$(OPENSSLDIR)/include
+		ALL_CFLAGS += -I$(OPENSSLDIR)/include
 		OPENSSL_LINK = -L$(OPENSSLDIR)/lib -R$(OPENSSLDIR)/lib
 	else
 		OPENSSL_LINK =
 	endif
 else
-	DEFINES += -DNO_OPENSSL
+	ALL_CFLAGS += -DNO_OPENSSL
 	MOZILLA_SHA1 = 1
 	OPENSSL_LIBSSL =
 endif
@@ -258,7 +307,7 @@ endif
 ifdef NEEDS_LIBICONV
 	ifdef ICONVDIR
 		# Again this may be problematic -- gcc does not always want -R.
-		CFLAGS += -I$(ICONVDIR)/include
+		ALL_CFLAGS += -I$(ICONVDIR)/include
 		ICONV_LINK = -L$(ICONVDIR)/lib -R$(ICONVDIR)/lib
 	else
 		ICONV_LINK =
@@ -276,15 +325,19 @@ ifdef NEEDS_NSL
 	SIMPLE_LIB += -lnsl
 endif
 ifdef NO_STRCASESTR
-	DEFINES += -Dstrcasestr=gitstrcasestr -DNO_STRCASESTR=1
+	COMPAT_CFLAGS += -DNO_STRCASESTR
-	LIB_OBJS += compat/strcasestr.o
+	COMPAT_OBJS += compat/strcasestr.o
+endif
+ifdef NO_SETENV
+	COMPAT_CFLAGS += -DNO_SETENV
+	COMPAT_OBJS += compat/setenv.o
 endif
 ifdef NO_MMAP
-	DEFINES += -Dmmap=gitfakemmap -Dmunmap=gitfakemunmap -DNO_MMAP
+	COMPAT_CFLAGS += -DNO_MMAP
-	LIB_OBJS += compat/mmap.o
+	COMPAT_OBJS += compat/mmap.o
 endif
 ifdef NO_IPV6
-	DEFINES += -DNO_IPV6 -Dsockaddr_storage=sockaddr_in
+	ALL_CFLAGS += -DNO_IPV6 -Dsockaddr_storage=sockaddr_in
 endif
 
 ifdef PPC_SHA1
@@ -305,31 +358,21 @@ endif
 endif
 endif
 
-DEFINES += -DSHA1_HEADER=$(call shellquote,$(SHA1_HEADER))
+ALL_CFLAGS += -DSHA1_HEADER=$(call shellquote,$(SHA1_HEADER)) $(COMPAT_CFLAGS)
-
+LIB_OBJS += $(COMPAT_OBJS)
-SCRIPTS = $(patsubst %.sh,%,$(SCRIPT_SH)) \
-	  $(patsubst %.perl,%,$(SCRIPT_PERL)) \
-	  $(patsubst %.py,%,$(SCRIPT_PYTHON)) \
-	  gitk git-cherry-pick
-
 export prefix TAR INSTALL DESTDIR SHELL_PATH template_dir
 ### Build rules
 
-all: $(PROGRAMS) $(SCRIPTS)
+all: $(ALL_PROGRAMS)
 
 all:
 	$(MAKE) -C templates
 
-git: git.sh Makefile
+git$X: git.c $(LIB_FILE) Makefile
-	rm -f $@+ $@
+	$(CC) -DGIT_EXEC_PATH='"$(bindir)"' -DGIT_VERSION='"$(GIT_VERSION)"' \
-	sed -e '1s|#!.*/sh|#!$(call shq,$(SHELL_PATH))|' \
+		$(CFLAGS) $(COMPAT_CFLAGS) -o $@ $(filter %.c,$^) $(LIB_FILE)
-	    -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' \
-	    -e 's/@@X@@/$(X)/g' \
-	    $(GIT_LIST_TWEAK) <$@.sh >$@+
-	chmod +x $@+
-	mv $@+ $@
 
-$(filter-out git,$(patsubst %.sh,%,$(SCRIPT_SH))) : % : %.sh
+$(patsubst %.sh,%,$(SCRIPT_SH)) : % : %.sh
 	rm -f $@
 	sed -e '1s|#!.*/sh|#!$(call shq,$(SHELL_PATH))|' \
 	    -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' \
@@ -354,20 +397,25 @@ $(patsubst %.py,%,$(SCRIPT_PYTHON)) : % : %.py
 git-cherry-pick: git-revert
 	cp $< $@
 
+# format-patch records GIT_VERSION
+git-format-patch: Makefile
+
 %.o: %.c
 	$(CC) -o $*.o -c $(ALL_CFLAGS) $<
 %.o: %.S
 	$(CC) -o $*.o -c $(ALL_CFLAGS) $<
 
 git-%$X: %.o $(LIB_FILE)
-	$(CC) $(ALL_CFLAGS) -o $@ $(filter %.o,$^) $(LIBS)
+	$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) $(LIBS)
 
 git-mailinfo$X : SIMPLE_LIB += $(LIB_4_ICONV)
 $(SIMPLE_PROGRAMS) : $(LIB_FILE)
 $(SIMPLE_PROGRAMS) : git-%$X : %.o
-	$(CC) $(ALL_CFLAGS) -o $@ $(filter %.o,$^) $(LIB_FILE) $(SIMPLE_LIB)
+	$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) \
+		$(LIB_FILE) $(SIMPLE_LIB)
 
-git-http-fetch$X: fetch.o
+git-http-fetch$X: fetch.o http.o
+git-http-push$X: http.o
 git-local-fetch$X: fetch.o
 git-ssh-fetch$X: rsh.o fetch.o
 git-ssh-upload$X: rsh.o
@@ -375,6 +423,7 @@ git-ssh-pull$X: rsh.o fetch.o
 git-ssh-push$X: rsh.o
 
 git-http-fetch$X: LIBS += $(CURL_LIBCURL)
+git-http-push$X: LIBS += $(CURL_LIBCURL) $(EXPAT_LIBEXPAT)
 git-rev-list$X: LIBS += $(OPENSSL_LIBSSL)
 
 init-db.o: init-db.c
@@ -398,21 +447,21 @@ test: all
 	$(MAKE) -C t/ all
 
 test-date$X: test-date.c date.o ctype.o
-	$(CC) $(ALL_CFLAGS) -o $@ test-date.c date.o ctype.o
+	$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) test-date.c date.o ctype.o
 
 test-delta$X: test-delta.c diff-delta.o patch-delta.o
-	$(CC) $(ALL_CFLAGS) -o $@ $^
+	$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $^
 
 check:
-	for i in *.c; do sparse $(ALL_CFLAGS) $(SPARSE_FLAGS) $$i; done
+	for i in *.c; do sparse $(ALL_CFLAGS) $(SPARSE_FLAGS) $$i || exit; done
 
 
 
 ### Installation rules
 
-install: $(PROGRAMS) $(SCRIPTS)
+install: all
 	$(INSTALL) -d -m755 $(call shellquote,$(DESTDIR)$(bindir))
-	$(INSTALL) $(PROGRAMS) $(SCRIPTS) $(call shellquote,$(DESTDIR)$(bindir))
+	$(INSTALL) $(ALL_PROGRAMS) $(call shellquote,$(DESTDIR)$(bindir))
 	$(MAKE) -C templates install
 	$(INSTALL) -d -m755 $(call shellquote,$(DESTDIR)$(GIT_PYTHON_DIR))
 	$(INSTALL) $(PYMODULES) $(call shellquote,$(DESTDIR)$(GIT_PYTHON_DIR))
@@ -425,37 +474,31 @@ install-doc:
 
 ### Maintainer's dist rules
 
-git-core.spec: git-core.spec.in Makefile
+git.spec: git.spec.in Makefile
 	sed -e 's/@@VERSION@@/$(GIT_VERSION)/g' < $< > $@
 
-GIT_TARNAME=git-core-$(GIT_VERSION)
+GIT_TARNAME=git-$(GIT_VERSION)
-dist: git-core.spec git-tar-tree
+dist: git.spec git-tar-tree
 	./git-tar-tree HEAD $(GIT_TARNAME) > $(GIT_TARNAME).tar
 	@mkdir -p $(GIT_TARNAME)
-	@cp git-core.spec $(GIT_TARNAME)
+	@cp git.spec $(GIT_TARNAME)
-	$(TAR) rf $(GIT_TARNAME).tar $(GIT_TARNAME)/git-core.spec
+	$(TAR) rf $(GIT_TARNAME).tar $(GIT_TARNAME)/git.spec
 	@rm -rf $(GIT_TARNAME)
 	gzip -f -9 $(GIT_TARNAME).tar
 
 rpm: dist
-	$(RPMBUILD) -ta git-core-$(GIT_VERSION).tar.gz
+	$(RPMBUILD) -ta $(GIT_TARNAME).tar.gz
-
-deb: dist
-	rm -rf $(GIT_TARNAME)
-	$(TAR) zxf $(GIT_TARNAME).tar.gz
-	dpkg-source -b $(GIT_TARNAME)
-	cd $(GIT_TARNAME) && fakeroot debian/rules binary
 
 ### Cleaning rules
 
 clean:
-	rm -f *.o mozilla-sha1/*.o ppc/*.o compat/*.o $(PROGRAMS) $(LIB_FILE)
+	rm -f *.o mozilla-sha1/*.o arm/*.o ppc/*.o compat/*.o $(LIB_FILE)
+	rm -f $(PROGRAMS) $(SIMPLE_PROGRAMS) git$X
 	rm -f $(filter-out gitk,$(SCRIPTS))
-	rm -f git-core.spec *.pyc *.pyo
+	rm -f *.spec *.pyc *.pyo */*.pyc */*.pyo
 	rm -rf $(GIT_TARNAME)
 	rm -f $(GIT_TARNAME).tar.gz git-core_$(GIT_VERSION)-*.tar.gz
-	rm -f git-core_$(GIT_VERSION)-*.deb git-core_$(GIT_VERSION)-*.dsc
-	rm -f git-tk_$(GIT_VERSION)-*.deb
 	$(MAKE) -C Documentation/ clean
 	$(MAKE) -C templates clean
 	$(MAKE) -C t/ clean
+

README

@@ -35,7 +35,7 @@ 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".
 
-A "blob" object cannot refer to any other object, and is, like the 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. 
@@ -64,7 +64,7 @@ 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
-that not only specifies their tag, but also provides size information
+that not only specifies their type, but also provides size information
 about the data in the object.  It's worth noting that the SHA1 hash
 that is used to name the object is the hash of the original data
 plus this header, so `sha1sum` 'file' does not match the object name
@@ -76,7 +76,7 @@ As a result, the general consistency of an object can always be tested
 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 tag without space> + <space> + <ascii decimal
+forms a sequence of <ascii type without space> + <space> + <ascii decimal
 size> + <byte\0> + <binary object data>. 
 
 The structured objects can further have their structure and
@@ -297,7 +297,7 @@ will not normally add totally new entries or remove old entries,
 i.e. it will normally just update existing cache entries.
 
 To tell git that yes, you really do realize that certain files no
-longer exist in the archive, or that new files should be added, you
+longer exist, or that new files should be added, you
 should use the `--remove` and `--add` flags respectively.
 
 NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
@@ -396,8 +396,8 @@ git-commit-tree will return the name of the object that represents
 that commit, and you should save it away for later use. Normally,
 you'd commit a new `HEAD` state, and while git doesn't care where you
 save the note about that state, in practice we tend to just write the
-result to the file `.git/HEAD`, so that we can always see what the
+result to the file pointed at by `.git/HEAD`, so that we can always see
-last committed state was.
+what the last committed state was.
 
 Here is an ASCII art by Jon Loeliger that illustrates how
 various pieces fit together.
@@ -464,7 +464,7 @@ tend to be small and fairly self-explanatory. In particular, if you
 follow the convention of having the top commit name in `.git/HEAD`,
 you can do
 
-		git-cat-file commit $(cat .git/HEAD)
+		git-cat-file commit HEAD
 
 to see what the top commit was.
 
@@ -515,8 +515,11 @@ index file, and you can just write the result out with
 Historical note.  We did not have `-u` facility when this
 section was first written, so we used to warn that
 the merge is done in the index file, not in your
-working directory, and your working directory will no longer match your
+working tree, and your working tree will not match your
-index.
+index after this step.
+This is no longer true.  The above command, thanks to `-u`
+option, updates your working tree with the merge results for
+paths that have been trivially merged.
 
 
 8) Merging multiple trees, continued
@@ -579,7 +582,7 @@ 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
-stages to temporary files and calls a `merge` script on it
+stages to temporary files and calls a "merge" script on it:
 
 	git-merge-index git-merge-one-file hello.c
 

apply.c

@@ -16,6 +16,10 @@
 //  --numstat does numeric diffstat, and doesn't actually apply
 //  --index-info shows the old and new index info for paths if available.
 //
+static const char *prefix;
+static int prefix_length = -1;
+
+static int allow_binary_replacement = 0;
 static int check_index = 0;
 static int write_index = 0;
 static int diffstat = 0;
@@ -23,10 +27,11 @@ static int numstat = 0;
 static int summary = 0;
 static int check = 0;
 static int apply = 1;
+static int no_add = 0;
 static int show_index_info = 0;
 static int line_termination = '\n';
 static const char apply_usage[] =
-"git-apply [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--index-info] [-z] <patch>...";
+"git-apply [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--index-info] [--allow-binary-replacement] [-z] <patch>...";
 
 /*
  * For "diff-stat" like behaviour, we keep track of the biggest change
@@ -53,7 +58,7 @@ struct fragment {
 struct patch {
 	char *new_name, *old_name, *def_name;
 	unsigned int old_mode, new_mode;
-	int is_rename, is_copy, is_new, is_delete;
+	int is_rename, is_copy, is_new, is_delete, is_binary;
 	int lines_added, lines_deleted;
 	int score;
 	struct fragment *fragments;
@@ -79,14 +84,11 @@ static void *read_patch_file(int fd, unsigned long *sizep)
 			buffer = xrealloc(buffer, alloc);
 			nr = alloc - size;
 		}
-		nr = read(fd, buffer + size, nr);
+		nr = xread(fd, buffer + size, nr);
 		if (!nr)
 			break;
-		if (nr < 0) {
+		if (nr < 0)
-			if (errno == EAGAIN)
-				continue;
 			die("git-apply: read returned %s", strerror(errno));
-		}
 		size += nr;
 	}
 	*sizep = size;
@@ -369,7 +371,7 @@ static int gitdiff_index(const char *line, struct patch *patch)
 	int len;
 
 	ptr = strchr(line, '.');
-	if (!ptr || ptr[1] != '.' || 40 <= ptr - line)
+	if (!ptr || ptr[1] != '.' || 40 < ptr - line)
 		return 0;
 	len = ptr - line;
 	memcpy(patch->old_sha1_prefix, line, len);
@@ -383,7 +385,7 @@ static int gitdiff_index(const char *line, struct patch *patch)
 		ptr = eol;
 	len = ptr - line;
 
-	if (40 <= len)
+	if (40 < len)
 		return 0;
 	memcpy(patch->new_sha1_prefix, line, len);
 	patch->new_sha1_prefix[len] = 0;
@@ -890,8 +892,36 @@ static int parse_chunk(char *buffer, unsigned long size, struct patch *patch)
 
 	patchsize = parse_single_patch(buffer + offset + hdrsize, size - offset - hdrsize, patch);
 
-	if (!patchsize && !metadata_changes(patch))
+	if (!patchsize) {
-		die("patch with only garbage at line %d", linenr);
+		static const char *binhdr[] = {
+			"Binary files ",
+			"Files ",
+			NULL,
+		};
+		int i;
+		int hd = hdrsize + offset;
+		unsigned long llen = linelen(buffer + hd, size - hd);
+
+		if (!memcmp(" differ\n", buffer + hd + llen - 8, 8))
+			for (i = 0; binhdr[i]; i++) {
+				int len = strlen(binhdr[i]);
+				if (len < size - hd &&
+				    !memcmp(binhdr[i], buffer + hd, len)) {
+					patch->is_binary = 1;
+					break;
+				}
+			}
+
+		/* Empty patch cannot be applied if:
+		 * - it is a binary patch and we do not do binary_replace, or
+		 * - text patch without metadata change
+		 */
+		if ((apply || check) &&
+		    (patch->is_binary
+		     ? !allow_binary_replacement
+		     : !metadata_changes(patch)))
+			die("patch with only garbage at line %d", linenr);
+	}
 
 	return offset + hdrsize + patchsize;
 }
@@ -949,9 +979,12 @@ static void show_stats(struct patch *patch)
 		add = (add * max + max_change / 2) / max_change;
 		del = total - add;
 	}
-	printf(" %s%-*s |%5d %.*s%.*s\n", prefix,
+	if (patch->is_binary)
-		len, name, patch->lines_added + patch->lines_deleted,
+		printf(" %s%-*s |  Bin\n", prefix, len, name);
-		add, pluses, del, minuses);
+	else
+		printf(" %s%-*s |%5d %.*s%.*s\n", prefix,
+		       len, name, patch->lines_added + patch->lines_deleted,
+		       add, pluses, del, minuses);
 	if (qname)
 		free(qname);
 }
@@ -970,13 +1003,8 @@ static int read_old_data(struct stat *st, const char *path, void *buf, unsigned
 			return error("unable to open %s", path);
 		got = 0;
 		for (;;) {
-			int ret = read(fd, buf + got, size - got);
+			int ret = xread(fd, buf + got, size - got);
-			if (ret < 0) {
+			if (ret <= 0)
-				if (errno == EAGAIN)
-					continue;
-				break;
-			}
-			if (!ret)
 				break;
 			got += ret;
 		}
@@ -1099,8 +1127,10 @@ static int apply_one_fragment(struct buffer_desc *desc, struct fragment *frag)
 				break;
 		/* Fall-through for ' ' */
 		case '+':
-			memcpy(new + newsize, patch + 1, plen);
+			if (*patch != '+' || !no_add) {
-			newsize += plen;
+				memcpy(new + newsize, patch + 1, plen);
+				newsize += plen;
+			}
 			break;
 		case '@': case '\\':
 			/* Ignore it, we already handled it */
@@ -1138,10 +1168,77 @@ static int apply_one_fragment(struct buffer_desc *desc, struct fragment *frag)
 static int apply_fragments(struct buffer_desc *desc, struct patch *patch)
 {
 	struct fragment *frag = patch->fragments;
+	const char *name = patch->old_name ? patch->old_name : patch->new_name;
+
+	if (patch->is_binary) {
+		unsigned char sha1[20];
+
+		if (!allow_binary_replacement)
+			return error("cannot apply binary patch to '%s' "
+				     "without --allow-binary-replacement",
+				     name);
+
+		/* For safety, we require patch index line to contain
+		 * full 40-byte textual SHA1 for old and new, at least for now.
+		 */
+		if (strlen(patch->old_sha1_prefix) != 40 ||
+		    strlen(patch->new_sha1_prefix) != 40 ||
+		    get_sha1_hex(patch->old_sha1_prefix, sha1) ||
+		    get_sha1_hex(patch->new_sha1_prefix, sha1))
+			return error("cannot apply binary patch to '%s' "
+				     "without full index line", name);
+
+		if (patch->old_name) {
+			unsigned char hdr[50];
+			int hdrlen;
+
+			/* See if the old one matches what the patch
+			 * applies to.
+			 */
+			write_sha1_file_prepare(desc->buffer, desc->size,
+						"blob", sha1, hdr, &hdrlen);
+			if (strcmp(sha1_to_hex(sha1), patch->old_sha1_prefix))
+				return error("the patch applies to '%s' (%s), "
+					     "which does not match the "
+					     "current contents.",
+					     name, sha1_to_hex(sha1));
+		}
+		else {
+			/* Otherwise, the old one must be empty. */
+			if (desc->size)
+				return error("the patch applies to an empty "
+					     "'%s' but it is not empty", name);
+		}
+
+		/* For now, we do not record post-image data in the patch,
+		 * and require the object already present in the recipient's
+		 * object database.
+		 */
+		if (desc->buffer) {
+			free(desc->buffer);
+			desc->alloc = desc->size = 0;
+		}
+		get_sha1_hex(patch->new_sha1_prefix, sha1);
+
+		if (memcmp(sha1, null_sha1, 20)) {
+			char type[10];
+			unsigned long size;
+
+			desc->buffer = read_sha1_file(sha1, type, &size);
+			if (!desc->buffer)
+				return error("the necessary postimage %s for "
+					     "'%s' does not exist",
+					     patch->new_sha1_prefix, name);
+			desc->alloc = desc->size = size;
+		}
+
+		return 0;
+	}
 
 	while (frag) {
 		if (apply_one_fragment(desc, frag) < 0)
-			return error("patch failed: %s:%ld", patch->old_name, frag->oldpos);
+			return error("patch failed: %s:%ld",
+				     name, frag->oldpos);
 		frag = frag->next;
 	}
 	return 0;
@@ -1183,6 +1280,7 @@ static int check_patch(struct patch *patch)
 	struct stat st;
 	const char *old_name = patch->old_name;
 	const char *new_name = patch->new_name;
+	const char *name = old_name ? old_name : new_name;
 
 	if (old_name) {
 		int changed;
@@ -1257,7 +1355,7 @@ static int check_patch(struct patch *patch)
 	}	
 
 	if (apply_data(patch, &st) < 0)
-		return error("%s: patch does not apply", old_name);
+		return error("%s: patch does not apply", name);
 	return 0;
 }
 
@@ -1490,16 +1588,13 @@ static int try_create_file(const char *path, unsigned int mode, const char *buf,
 
 	if (S_ISLNK(mode))
 		return symlink(buf, path);
-	fd = open(path, O_CREAT | O_EXCL | O_WRONLY | O_TRUNC, (mode & 0100) ? 0777 : 0666);
+	fd = open(path, O_CREAT | O_EXCL | O_WRONLY, (mode & 0100) ? 0777 : 0666);
 	if (fd < 0)
 		return -1;
 	while (size) {
-		int written = write(fd, buf, size);
+		int written = xwrite(fd, buf, size);
-		if (written < 0) {
+		if (written < 0)
-			if (errno == EINTR || errno == EAGAIN)
-				continue;
 			die("writing file %s: %s", path, strerror(errno));
-		}
 		if (!written)
 			die("out of space writing file %s", path);
 		buf += written;
@@ -1540,7 +1635,8 @@ static void create_one_file(const char *path, unsigned mode, const char *buf, un
 			}
 			if (errno != EEXIST)
 				break;
-		}			
+			++nr;
+		}
 	}
 	die("unable to write file %s mode %o", path, mode);
 }
@@ -1603,6 +1699,12 @@ static int use_patch(struct patch *p)
 			return 0;
 		x = x->next;
 	}
+	if (0 < prefix_length) {
+		int pathlen = strlen(pathname);
+		if (pathlen <= prefix_length ||
+		    memcmp(prefix, pathname, prefix_length))
+			return 0;
+	}
 	return 1;
 }
 
@@ -1697,11 +1799,19 @@ int main(int argc, char **argv)
 			excludes = x;
 			continue;
 		}
+		if (!strcmp(arg, "--no-add")) {
+			no_add = 1;
+			continue;
+		}
 		if (!strcmp(arg, "--stat")) {
 			apply = 0;
 			diffstat = 1;
 			continue;
 		}
+		if (!strcmp(arg, "--allow-binary-replacement")) {
+			allow_binary_replacement = 1;
+			continue;
+		}
 		if (!strcmp(arg, "--numstat")) {
 			apply = 0;
 			numstat = 1;
@@ -1734,6 +1844,15 @@ int main(int argc, char **argv)
 			line_termination = 0;
 			continue;
 		}
+
+		if (check_index && prefix_length < 0) {
+			prefix = setup_git_directory();
+			prefix_length = prefix ? strlen(prefix) : 0;
+			git_config(git_default_config);
+		}
+		if (0 < prefix_length)
+			arg = prefix_filename(prefix, prefix_length, arg);
+
 		fd = open(arg, O_RDONLY);
 		if (fd < 0)
 			usage(apply_usage);

blob.c

@@ -1,5 +1,5 @@
-#include "blob.h"
 #include "cache.h"
+#include "blob.h"
 #include <stdlib.h>
 
 const char *blob_type = "blob";

cache.h

@@ -1,23 +1,7 @@
 #ifndef CACHE_H
 #define CACHE_H
 
-#include <unistd.h>
+#include "git-compat-util.h"
-#include <stdio.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <stddef.h>
-#include <stdlib.h>
-#include <stdarg.h>
-#include <string.h>
-#include <errno.h>
-#include <limits.h>
-#ifndef NO_MMAP
-#include <sys/mman.h>
-#endif
-#include <sys/param.h>
-#include <netinet/in.h>
-#include <sys/types.h>
-#include <dirent.h>
 
 #include SHA1_HEADER
 #include <zlib.h>
@@ -36,15 +20,6 @@
 #define DTYPE(de)	DT_UNKNOWN
 #endif
 
-#ifdef __GNUC__
-#define NORETURN __attribute__((__noreturn__))
-#else
-#define NORETURN
-#ifndef __attribute__
-#define __attribute__(x)
-#endif
-#endif
-
 /*
  * Intensive research over the course of many years has shown that
  * port 9418 is totally unused by anything else. Or
@@ -106,7 +81,7 @@ struct cache_entry {
 	unsigned int ce_size;
 	unsigned char sha1[20];
 	unsigned short ce_flags;
-	char name[0];
+	char name[FLEX_ARRAY]; /* more */
 };
 
 #define CE_NAMEMASK  (0x0fff)
@@ -147,8 +122,10 @@ extern char *get_graft_file(void);
 #define ALTERNATE_DB_ENVIRONMENT "GIT_ALTERNATE_OBJECT_DIRECTORIES"
 
 extern const char **get_pathspec(const char *prefix, const char **pathspec);
+extern const char *setup_git_directory_gently(int *);
 extern const char *setup_git_directory(void);
 extern const char *prefix_path(const char *prefix, int len, const char *path);
+extern const char *prefix_filename(const char *prefix, int len, const char *path);
 
 #define alloc_nr(x) (((x)+16)*3/2)
 
@@ -167,6 +144,7 @@ extern int ce_match_stat(struct cache_entry *ce, struct stat *st);
 extern int ce_modified(struct cache_entry *ce, struct stat *st);
 extern int ce_path_match(const struct cache_entry *ce, const char **pathspec);
 extern int index_fd(unsigned char *sha1, int fd, struct stat *st, int write_object, const char *type);
+extern int index_pipe(unsigned char *sha1, int fd, const char *type, int write_object);
 extern int index_path(unsigned char *sha1, const char *path, struct stat *st, int write_object);
 extern void fill_stat_cache_info(struct cache_entry *ce, struct stat *st);
 
@@ -179,6 +157,12 @@ extern int commit_index_file(struct cache_file *);
 extern void rollback_index_file(struct cache_file *);
 
 extern int trust_executable_bit;
+extern int only_use_symrefs;
+extern int diff_rename_limit_default;
+
+#define GIT_REPO_VERSION 0
+extern int repository_format_version;
+extern int check_repository_format(void);
 
 #define MTIME_CHANGED	0x0001
 #define CTIME_CHANGED	0x0002
@@ -201,6 +185,7 @@ int git_mkstemp(char *path, size_t n, const char *template);
 
 int safe_create_leading_directories(char *path);
 char *safe_strncpy(char *, const char *, size_t);
+char *enter_repo(char *path, int strict);
 
 /* Read and unpack a sha1 file into memory, write memory to a sha1 file */
 extern int unpack_sha1_header(z_stream *stream, void *map, unsigned long mapsize, void *buffer, unsigned long size);
@@ -241,11 +226,6 @@ extern const char *resolve_ref(const char *path, unsigned char *sha1, int);
 extern int create_symref(const char *git_HEAD, const char *refs_heads_master);
 extern int validate_symref(const char *git_HEAD);
 
-/* General helper functions */
-extern void usage(const char *err) NORETURN;
-extern void die(const char *err, ...) NORETURN __attribute__((format (printf, 1, 2)));
-extern int error(const char *err, ...) __attribute__((format (printf, 1, 2)));
-
 extern int base_name_compare(const char *name1, int len1, int mode1, const char *name2, int len2, int mode2);
 extern int cache_name_compare(const char *name1, int len1, const char *name2, int len2);
 
@@ -257,35 +237,11 @@ extern void *read_object_with_reference(const unsigned char *sha1,
 const char *show_date(unsigned long time, int timezone);
 int parse_date(const char *date, char *buf, int bufsize);
 void datestamp(char *buf, int bufsize);
+unsigned long approxidate(const char *);
 
 extern int setup_ident(void);
-extern char *get_ident(const char *name, const char *email, const char *date_str);
+extern const char *git_author_info(void);
-extern char *git_author_info(void);
+extern const char *git_committer_info(void);
-extern char *git_committer_info(void);
-
-static inline void *xmalloc(size_t size)
-{
-	void *ret = malloc(size);
-	if (!ret)
-		die("Out of memory, malloc failed");
-	return ret;
-}
-
-static inline void *xrealloc(void *ptr, size_t size)
-{
-	void *ret = realloc(ptr, size);
-	if (!ret)
-		die("Out of memory, realloc failed");
-	return ret;
-}
-
-static inline void *xcalloc(size_t nmemb, size_t size)
-{
-	void *ret = calloc(nmemb, size);
-	if (!ret)
-		die("Out of memory, calloc failed");
-	return ret;
-}
 
 struct checkout {
 	const char *base_dir;
@@ -301,7 +257,7 @@ extern int checkout_entry(struct cache_entry *ce, struct checkout *state);
 extern struct alternate_object_database {
 	struct alternate_object_database *next;
 	char *name;
-	char base[0]; /* more */
+	char base[FLEX_ARRAY]; /* more */
 } *alt_odb_list;
 extern void prepare_alt_odb(void);
 
@@ -315,7 +271,8 @@ extern struct packed_git {
 	unsigned int pack_use_cnt;
 	int pack_local;
 	unsigned char sha1[20];
-	char pack_name[0]; /* something like ".git/objects/pack/xxxxx.pack" */
+	/* something like ".git/objects/pack/xxxxx.pack" */
+	char pack_name[FLEX_ARRAY]; /* more */
 } *packed_git;
 
 struct pack_entry {
@@ -330,7 +287,7 @@ struct ref {
 	unsigned char new_sha1[20];
 	unsigned char force;
 	struct ref *peer_ref; /* when renaming */
-	char name[0];
+	char name[FLEX_ARRAY]; /* more */
 };
 
 extern int git_connect(int fd[2], char *url, const char *prog);
@@ -364,55 +321,27 @@ extern void packed_object_info_detail(struct pack_entry *, char *, unsigned long
 /* Dumb servers support */
 extern int update_server_info(int);
 
-#ifdef NO_MMAP
-
-#ifndef PROT_READ
-#define PROT_READ 1
-#define PROT_WRITE 2
-#define MAP_PRIVATE 1
-#define MAP_FAILED ((void*)-1)
-#endif
-
-extern void *gitfakemmap(void *start, size_t length, int prot , int flags, int fd, off_t offset);
-extern int gitfakemunmap(void *start, size_t length);
-
-#endif
-
 typedef int (*config_fn_t)(const char *, const char *);
 extern int git_default_config(const char *, const char *);
+extern int git_config_from_file(config_fn_t fn, const char *);
 extern int git_config(config_fn_t fn);
 extern int git_config_int(const char *, const char *);
 extern int git_config_bool(const char *, const char *);
+extern int git_config_set(const char *, const char *);
+extern int git_config_set_multivar(const char *, const char *, const char *, int);
+extern int check_repository_format_version(const char *var, const char *value);
 
 #define MAX_GITNAME (1000)
 extern char git_default_email[MAX_GITNAME];
 extern char git_default_name[MAX_GITNAME];
 
-/* Sane ctype - no locale, and works with signed chars */
+#define MAX_ENCODING_LENGTH 64
-#undef isspace
+extern char git_commit_encoding[MAX_ENCODING_LENGTH];
-#undef isdigit
-#undef isalpha
-#undef isalnum
-#undef tolower
-#undef toupper
-extern unsigned char sane_ctype[256];
-#define GIT_SPACE 0x01
-#define GIT_DIGIT 0x02
-#define GIT_ALPHA 0x04
-#define sane_istest(x,mask) ((sane_ctype[(unsigned char)(x)] & (mask)) != 0)
-#define isspace(x) sane_istest(x,GIT_SPACE)
-#define isdigit(x) sane_istest(x,GIT_DIGIT)
-#define isalpha(x) sane_istest(x,GIT_ALPHA)
-#define isalnum(x) sane_istest(x,GIT_ALPHA | GIT_DIGIT)
-#define tolower(x) sane_case((unsigned char)(x), 0x20)
-#define toupper(x) sane_case((unsigned char)(x), 0)
-
-static inline int sane_case(int x, int high)
-{
-	if (sane_istest(x, GIT_ALPHA))
-		x = (x & ~0x20) | high;
-	return x;
-}
 
 extern int copy_fd(int ifd, int ofd);
+
+/* Finish off pack transfer receiving end */
+extern int receive_unpack_pack(int fd[2], const char *me, int quiet);
+extern int receive_keep_pack(int fd[2], const char *me);
+
 #endif /* CACHE_H */

cat-file.c

@@ -11,37 +11,52 @@ int main(int argc, char **argv)
 	char type[20];
 	void *buf;
 	unsigned long size;
+	int opt;
 
 	setup_git_directory();
 	if (argc != 3 || get_sha1(argv[2], sha1))
-		usage("git-cat-file [-t | -s | <type>] <sha1>");
+		usage("git-cat-file [-t|-s|-e|<type>] <sha1>");
 
-	if (!strcmp("-t", argv[1]) || !strcmp("-s", argv[1])) {
+	opt = 0;
-		if (!sha1_object_info(sha1, type,
+	if ( argv[1][0] == '-' ) {
-				      argv[1][1] == 's' ? &size : NULL)) {
+		opt = argv[1][1];
-			switch (argv[1][1]) {
+		if ( !opt || argv[1][2] )
-			case 't':
+			opt = -1; /* Not a single character option */
-				printf("%s\n", type);
+	}
-				break;
+
-			case 's':
+	buf = NULL;
-				printf("%lu\n", size);
+	switch (opt) {
-				break;
+	case 't':
-			}
+		if (!sha1_object_info(sha1, type, NULL)) {
+			printf("%s\n", type);
 			return 0;
 		}
-		buf = NULL;
+		break;
-	} else {
+
+	case 's':
+		if (!sha1_object_info(sha1, type, &size)) {
+			printf("%lu\n", size);
+			return 0;
+		}
+		break;
+
+	case 'e':
+		return !has_sha1_file(sha1);
+
+	case 0:
 		buf = read_object_with_reference(sha1, argv[1], &size, NULL);
+		break;
+
+	default:
+		die("git-cat-file: unknown option: %s\n", argv[1]);
 	}
 
 	if (!buf)
 		die("git-cat-file %s: bad file", argv[2]);
 
 	while (size > 0) {
-		long ret = write(1, buf, size);
+		long ret = xwrite(1, buf, size);
 		if (ret < 0) {
-			if (errno == EAGAIN)
-				continue;
 			/* Ignore epipe */
 			if (errno == EPIPE)
 				break;