Merge branch 'sp/keep-pack' into np/index-pack

* sp/keep-pack: (29 commits)
  Remove unused variable in receive-pack.
  Teach git-index-pack how to keep a pack file.
  Only repack active packs by skipping over kept packs.
  Allow short pack names to git-pack-objects --unpacked=.
  git-send-email: Read the default SMTP server from the GIT config file
  git-send-email: Document support for local sendmail instead of SMTP server
  Swap the porcelain and plumbing commands in the git man page
  Mention that pull can work locally in the synopsis
  gitweb: Add "next" link to commitdiff view
  gitweb: Move git_get_last_activity subroutine earlier
  Documentation: fix git-format-patch mark-up and link it from git.txt
  Documentation: Update information about <format> in git-for-each-ref
  Bash completion support for aliases
  gitweb: Fix up bogus $stylesheet declarations
  tests: merge-recursive is usable without Python
  gitweb: Check git base URLs before generating URL from it
  Documentation: add git in /etc/services.
  Documentation: add upload-archive service to git-daemon.
  git-cherry: document limit and add diagram
  diff-format.txt: Correct information about pathnames quoting in patch format
  ...

10 files changed, 364 insertions, 242 deletions

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 617d8f526..e4520e28e 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -144,8 +144,10 @@ the file that rename/copy produces, respectively.
        dissimilarity index <number>
        index <hash>..<hash> <mode>
 
-3.  TAB, LF, and backslash characters in pathnames are
-    represented as `\t`, `\n`, and `\\`, respectively.
+3.  TAB, LF, double quote and backslash characters in pathnames
+    are represented as `\t`, `\n`, `\"` and `\\`, respectively.
+    If there is need for such substitution then the whole
+    pathname is put in double quotes.
 
 
 combined diff format
@@ -156,31 +158,91 @@ to produce 'combined diff', which looks like this:
 
 ------------
 diff --combined describe.c
-@@@ +98,7 @@@
-   return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+  	return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
   }
-
+  
 - static void describe(char *arg)
  -static void describe(struct commit *cmit, int last_one)
 ++static void describe(char *arg, int last_one)
   {
- +     unsigned char sha1[20];
- +     struct commit *cmit;
+ +	unsigned char sha1[20];
+ +	struct commit *cmit;
+  	struct commit_list *list;
+  	static int initialized = 0;
+  	struct commit_name *n;
+  
+ +	if (get_sha1(arg, sha1) < 0)
+ +		usage(describe_usage);
+ +	cmit = lookup_commit_reference(sha1);
+ +	if (!cmit)
+ +		usage(describe_usage);
+ +
+  	if (!initialized) {
+  		initialized = 1;
+  		for_each_ref(get_name);
 ------------
 
+1.   It is preceded with a "git diff" header, that looks like
+     this (when '-c' option is used):
+
+       diff --combined file
++
+or like this (when '--cc' option is used):
+
+       diff --c file
+
+2.   It is followed by one or more extended header lines
+     (this example shows a merge with two parents):
+
+       index <hash>,<hash>..<hash>
+       mode <mode>,<mode>..<mode>
+       new file mode <mode>
+       deleted file mode <mode>,<mode>
++
+The `mode <mode>,<mode>..<mode>` line appears only if at least one of
+the <mode> is diferent from the rest. Extended headers with
+information about detected contents movement (renames and
+copying detection) are designed to work with diff of two
+<tree-ish> and are not used by combined diff format.
+
+3.   It is followed by two-line from-file/to-file header
+
+       --- a/file
+       +++ b/file
++
+Similar to two-line header for traditional 'unified' diff
+format, `/dev/null` is used to signal created or deleted
+files.
+
+4.   Chunk header format is modified to prevent people from
+     accidentally feeding it to `patch -p1`. Combined diff format
+     was created for review of merge commit changes, and was not
+     meant for apply. The change is similar to the change in the
+     extended 'index' header:
+
+       @@@ <from-file-range> <from-file-range> <to-file-range> @@@
++
+There are (number of parents + 1) `@` characters in the chunk
+header for combined diff format.
+
 Unlike the traditional 'unified' diff format, which shows two
 files A and B with a single column that has `-` (minus --
 appears in A but removed in B), `+` (plus -- missing in A but
-added to B), or ` ` (space -- unchanged) prefix, this format
+added to B), or `" "` (space -- unchanged) prefix, this format
 compares two or more files file1, file2,... with one file X, and
 shows how X differs from each of fileN.  One column for each of
 fileN is prepended to the output line to note how X's line is
 different from it.
 
 A `-` character in the column N means that the line appears in
-fileN but it does not appear in the last file.  A `+` character
+fileN but it does not appear in the result.  A `+` character
 in the column N means that the line appears in the last file,
-and fileN does not have that line.
+and fileN does not have that line (in other words, the line was
+added, from the point of view of that parent).
 
 In the above example output, the function signature was changed
 from both files (hence two `-` removals from both file1 and
diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index b935c1808..967767189 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -1,22 +1,7 @@
 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
+<<Basic Repository>> commands are needed by people who have a
 repository --- that is everybody, because every working tree of
 git is a repository.
 
@@ -25,28 +10,27 @@ 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.
+the <<Individual Developer (Participant)>> section as well.
 
-People who play <<Integrator>> role need to learn some more
+People who play the <<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.
+administrators who are responsible for the care and feeding
+of git repositories.
 
 
 Basic Repository[[Basic Repository]]
 ------------------------------------
 
-Everybody uses these commands to feed and care git repositories.
+Everybody uses these commands to maintain 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-fsck-objects[1] to check the repository for errors.
 
-  * gitlink:git-prune[1] to garbage collect cruft in the
-    repository.
+  * gitlink:git-prune[1] to remove unused objects in the repository.
 
   * gitlink:git-repack[1] to pack loose objects for efficiency.
 
@@ -78,8 +62,8 @@ $ git repack -a -d <1>
 $ git prune
 ------------
 +
-<1> pack all the objects reachable from the refs into one pack
-and remove unneeded other packs
+<1> pack all the objects reachable from the refs into one pack,
+then remove the other packs.
 
 
 Individual Developer (Standalone)[[Individual Developer (Standalone)]]
@@ -93,9 +77,6 @@ following commands.
 
   * 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.
 
@@ -120,7 +101,7 @@ following commands.
 Examples
 ~~~~~~~~
 
-Extract a tarball and create a working tree and a new repository to keep track of it.::
+Use a tarball as a starting point for a new repository:
 +
 ------------
 $ tar zxf frotz.tar.gz
@@ -203,7 +184,7 @@ $ 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 log -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>
@@ -372,12 +353,19 @@ example of managing a shared central repository.
 
 Examples
 ~~~~~~~~
+We assume the following in /etc/services::
++
+------------
+$ grep 9418 /etc/services
+git		9418/tcp		# Git Version Control System
+------------
+
 Run git-daemon to serve /pub/scm from inetd.::
 +
 ------------
 $ grep git /etc/inetd.conf
 git	stream	tcp	nowait	nobody \
-  /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
 ------------
 +
 The actual configuration line should be on one line.
@@ -397,7 +385,7 @@ service git
         wait            = no
         user            = nobody
         server          = /usr/bin/git-daemon
-        server_args     = --inetd --syslog --export-all --base-path=/pub/scm
+        server_args     = --inetd --export-all --base-path=/pub/scm
         log_on_failure  += USERID
 }
 ------------
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt
index e1bf8ee25..27b67b81a 100644
--- a/Documentation/git-cherry.txt
+++ b/Documentation/git-cherry.txt
@@ -7,7 +7,7 @@ git-cherry - Find commits not merged upstream
 
 SYNOPSIS
 --------
-'git-cherry' [-v] <upstream> [<head>]
+'git-cherry' [-v] <upstream> [<head>] [<limit>]
 
 DESCRIPTION
 -----------
@@ -18,7 +18,22 @@ Every commit that doesn't exist in the <upstream> branch
 has its id (sha1) reported, prefixed by a symbol.  The ones that have
 equivalent change already
 in the <upstream> branch are prefixed with a minus (-) sign, and those
-that only exist in the <head> branch are prefixed with a plus (+) symbol.
+that only exist in the <head> branch are prefixed with a plus (+) symbol:
+
+               __*__*__*__*__> <upstream>
+              /
+    fork-point
+              \__+__+__-__+__+__-__+__> <head>
+
+
+If a <limit> has been given then the commits along the <head> branch up
+to and including <limit> are not reported:
+
+               __*__*__*__*__> <upstream>
+              /
+    fork-point
+              \__*__*__<limit>__-__+__> <head>
+
 
 Because git-cherry compares the changeset rather than the commit id
 (sha1), you can use git-cherry to find out if a commit you made locally
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index d562232e5..993adc7c5 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -37,6 +37,8 @@ from `git-fetch`, `git-ls-remote`, and `git-clone`.
 This is ideally suited for read-only updates, i.e., pulling from
 git repositories.
 
+An `upload-archive` also exists to serve `git-archive`.
+
 OPTIONS
 -------
 --strict-paths::
@@ -155,8 +157,18 @@ upload-pack::
 	disable it by setting `daemon.uploadpack` configuration
 	item to `false`.
 
+upload-archive::
+	This serves `git-archive --remote`.
+
 EXAMPLES
 --------
+We assume the following in /etc/services::
++
+------------
+$ grep 9418 /etc/services
+git		9418/tcp		# Git Version Control System
+------------
+
 git-daemon as inetd server::
 	To set up `git-daemon` as an inetd service that handles any
 	repository under the whitelisted set of directories, /pub/foo
@@ -165,8 +177,7 @@ git-daemon as inetd server::
 +
 ------------------------------------------------
 	git stream tcp nowait nobody  /usr/bin/git-daemon
-		git-daemon --inetd --verbose
-		--syslog --export-all
+		git-daemon --inetd --verbose --export-all
 		/pub/foo /pub/bar
 ------------------------------------------------
 
@@ -179,8 +190,7 @@ git-daemon as inetd server for virtual hosts::
 +
 ------------------------------------------------
 	git stream tcp nowait nobody /usr/bin/git-daemon
-		git-daemon --inetd --verbose
-		--syslog --export-all
+		git-daemon --inetd --verbose --export-all
 		--interpolated-path=/pub/%H%D
 		/pub/www.example.org/software
 		/pub/www.example.com/software
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d5fdcef8d..2bf6aef73 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -7,14 +7,14 @@ git-for-each-ref - Output information on each ref
 
 SYNOPSIS
 --------
-'git-for-each-ref' [--count=<count>]* [--shell|--perl|--python] [--sort=<key>]* [--format=<format>] [<pattern>]
+'git-for-each-ref' [--count=<count>]\* [--shell|--perl|--python] [--sort=<key>]\* [--format=<format>] [<pattern>]
 
 DESCRIPTION
 -----------
 
 Iterate over all refs that match `<pattern>` and show them
 according to the given `<format>`, after sorting them according
-to the given set of `<key>`s.  If `<max>` is given, stop after
+to the given set of `<key>`.  If `<max>` is given, stop after
 showing that many refs.  The interporated values in `<format>`
 can optionally be quoted as string literals in the specified
 host language allowing their direct evaluation in that language.
@@ -38,7 +38,11 @@ OPTIONS
 	is prefixed with an asterisk (`*`) and the ref points
 	at a tag object, the value for the field in the object
 	tag refers is used.  When unspecified, defaults to
-	`%(refname)`.
+	`%(objectname) SPC %(objecttype) TAB %(refname)`.
+	It also interpolates `%%` to `%`, and `%xx` where `xx`
+	are hex digits interpolates to character with hex code
+	`xx`; for example `%00` interpolates to `\0` (NUL),
+	`%09` to `\t` (TAB) and `%0a` to `\n` (LF).
 
 <pattern>::
 	If given, the name of the ref is matched against this
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 9fa4847d5..1235416e0 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -9,7 +9,7 @@ git-index-pack - Build pack index file for an existing packed archive
 SYNOPSIS
 --------
 'git-index-pack' [-v] [-o <index-file>] <pack-file>
-'git-index-pack' --stdin [--fix-thin] [-v] [-o <index-file>] [<pack-file>]
+'git-index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] [<pack-file>]
 
 
 DESCRIPTION
@@ -38,7 +38,10 @@ OPTIONS
 	instead and a copy is then written to <pack-file>. If
 	<pack-file> is not specified, the pack is written to
 	objects/pack/ directory of the current git repository with
-	a default name determined from the pack content.
+	a default name determined from the pack content.  If
+	<pack-file> is not specified consider using --keep to
+	prevent a race condition between this process and
+	gitlink::git-repack[1] .
 
 --fix-thin::
 	It is possible for gitlink:git-pack-objects[1] to build
@@ -48,7 +51,22 @@ OPTIONS
 	and they must be included in the pack for that pack to be self
 	contained and indexable. Without this option any attempt to
 	index a thin pack will fail. This option only makes sense in
-	conjonction with --stdin.
+	conjunction with --stdin.
+
+--keep::
+	Before moving the index into its final destination
+	create an empty .keep file for the associated pack file.
+	This option is usually necessary with --stdin to prevent a
+	simultaneous gitlink:git-repack[1] process from deleting
+	the newly constructed pack and index before refs can be
+	updated to use objects contained in the pack.
+
+--keep='why'::
+	Like --keep create a .keep file before moving the index into
+	its final destination, but rather than creating an empty file
+	place 'why' followed by an LF into the .keep file.  The 'why'
+	message can later be searched for within all .keep files to
+	locate any which have outlived their usefulness.
 
 
 Author
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 51577fcbe..2a5aea73b 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -3,7 +3,7 @@ git-pull(1)
 
 NAME
 ----
-git-pull - Pull and merge from another repository
+git-pull - Pull and merge from another repository or a local branch
 
 
 SYNOPSIS
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 5d4257062..ed938aafb 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -122,14 +122,30 @@ blobs contained in a commit.
   your repository whose object name starts with dae86e.
 
 * An output from `git-describe`; i.e. a closest tag, followed by a
-  dash, a 'g', and an abbreviated object name.
+  dash, a `g`, and an abbreviated object name.
 
 * A symbolic ref name.  E.g. 'master' typically means the commit
   object referenced by $GIT_DIR/refs/heads/master.  If you
   happen to have both heads/master and tags/master, you can
   explicitly say 'heads/master' to tell git which one you mean.
+  When ambiguous, a `<name>` is disambiguated by taking the
+  first match in the following rules:
 
-* A suffix '@' followed by a date specification enclosed in a brace
+  . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
+    useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
+
+  . otherwise, `$GIT_DIR/refs/<name>` if exists;
+
+  . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+
+  . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+
+  . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+
+  . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+
+* A ref followed by the suffix '@' with a date specification
+  enclosed in a brace
   pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
   of the ref at a prior point in time.  This suffix may only be
@@ -146,8 +162,9 @@ blobs contained in a commit.
 * A suffix '{tilde}<n>' to a revision parameter means the commit
   object that is the <n>th generation grand-parent of the named
   commit object, following only the first parent.  I.e. rev~3 is
-  equivalent to rev{caret}{caret}{caret} which is equivalent to\
-  rev{caret}1{caret}1{caret}1.
+  equivalent to rev{caret}{caret}{caret} which is equivalent to
+  rev{caret}1{caret}1{caret}1.  See below for a illustration of
+  the usage of this form.
 
 * A suffix '{caret}' followed by an object type name enclosed in
   brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 481b3f50e..4c8d907bd 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -66,8 +66,13 @@ The options available are:
 	all that is output.
 
 --smtp-server::
-	If set, specifies the outgoing SMTP server to use.  Defaults to
-	localhost.
+	If set, specifies the outgoing SMTP server to use.  A full
+	pathname of a sendmail-like program can be specified instead;
+	the program must support the `-i` option.  Default value can
+	be specified by the 'sendemail.smtpserver' configuration
+	option; the built-in default is `/usr/sbin/sendmail` or
+	`/usr/lib/sendmail` if such program is available, or
+	`localhost` otherwise.
 
 --subject::
    	Specify the initial subject of the email thread.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b00607ee1..0679e3c20 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -72,185 +72,6 @@ GIT COMMANDS
 We divide git into high level ("porcelain") commands and low level
 ("plumbing") commands.
 
-Low-level commands (plumbing)
------------------------------
-
-Although git includes its
-own porcelain layer, its low-level commands are sufficient to support
-development of alternative porcelains.  Developers of such porcelains
-might start by reading about gitlink:git-update-index[1] and
-gitlink:git-read-tree[1].
-
-We divide the low-level commands into commands that manipulate objects (in
-the repository, index, and working tree), commands that interrogate and
-compare objects, and commands that move objects and references between
-repositories.
-
-Manipulation commands
-~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-apply[1]::
-	Reads a "diff -up1" or git generated patch file and
-	applies it to the working tree.
-
-gitlink:git-checkout-index[1]::
-	Copy files from the index to the working tree.
-
-gitlink:git-commit-tree[1]::
-	Creates a new commit object.
-
-gitlink:git-hash-object[1]::
-	Computes the object ID from a file.
-
-gitlink:git-index-pack[1]::
-	Build pack idx file for an existing packed archive.
-
-gitlink:git-init-db[1]::
-	Creates an empty git object database, or reinitialize an
-	existing one.
-
-gitlink:git-merge-index[1]::
-	Runs a merge for files needing merging.
-
-gitlink:git-mktag[1]::
-	Creates a tag object.
-
-gitlink:git-mktree[1]::
-	Build a tree-object from ls-tree formatted text.
-
-gitlink:git-pack-objects[1]::
-	Creates a packed archive of objects.
-
-gitlink:git-prune-packed[1]::
-	Remove extra objects that are already in pack files.
-
-gitlink:git-read-tree[1]::
-	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]::
-	Registers files in the working tree to the index.
-
-gitlink:git-write-tree[1]::
-	Creates a tree from the index.
-
-
-Interrogation commands
-~~~~~~~~~~~~~~~~~~~~~~
-
-gitlink:git-cat-file[1]::
-	Provide content or type/size information for repository objects.
-
-gitlink:git-describe[1]::
-	Show the most recent tag that is reachable from a commit.
-
-gitlink:git-diff-index[1]::
-	Compares content and mode of blobs between the index and repository.
-
-gitlink:git-diff-files[1]::
-	Compares files in the working tree and the index.
-
-gitlink:git-diff-stages[1]::
-	Compares two "merge stages" in the index.
-
-gitlink:git-diff-tree[1]::
-	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.
-
-gitlink:git-ls-files[1]::
-	Information about files in the index and the working tree.
-
-gitlink:git-ls-tree[1]::
-	Displays a tree object in human readable form.
-
-gitlink:git-merge-base[1]::
-	Finds as good common ancestors as possible for a merge.
-
-gitlink:git-name-rev[1]::
-	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.
-
-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 object.
-
-gitlink:git-unpack-file[1]::
-	Creates a temporary file with a blob's contents.
-
-gitlink:git-var[1]::
-	Displays a git logical variable.
-
-gitlink:git-verify-pack[1]::
-	Validates packed git archive files.
-
-In general, the interrogate commands do not touch the files in
-the working tree.
-
-
-Synching repositories
-~~~~~~~~~~~~~~~~~~~~~
-
-gitlink:git-fetch-pack[1]::
-	Updates from a remote repository (engine for ssh and
-	local transport).
-
-gitlink:git-http-fetch[1]::
-	Downloads a remote git repository via HTTP by walking
-	commit chain.
-
-gitlink:git-local-fetch[1]::
-	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 (engine for ssh and local
-	transport).
-
-gitlink:git-receive-pack[1]::
-	Invoked by 'git-send-pack' to receive what is pushed to it.
-
-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 by
-	walking commit chain.
-
-gitlink:git-ssh-upload[1]::
-	Helper "server-side" program used by git-ssh-fetch.
-
-gitlink:git-update-server-info[1]::
-	Updates auxiliary information on a dumb server to help
-	clients discover references and packs on it.
-
-gitlink:git-upload-archive[1]::
-	Invoked by 'git-archive' to send a generated archive.
-
-gitlink:git-upload-pack[1]::
-	Invoked by 'git-fetch-pack' to push
-	what are asked for.
-
-
 High-level commands (porcelain)
 -------------------------------
 
@@ -321,7 +142,7 @@ gitlink:git-mv[1]::
 	Move or rename a file, a directory, or a symlink.
 
 gitlink:git-pull[1]::
-	Fetch from and merge with a remote repository.
+	Fetch from and merge with a remote repository or a local branch.
 
 gitlink:git-push[1]::
 	Update remote refs along with associated objects.
@@ -488,6 +309,188 @@ gitlink:git-stripspace[1]::
 	Filter out empty lines.
 
 
+Low-level commands (plumbing)
+-----------------------------
+
+Although git includes its
+own porcelain layer, its low-level commands are sufficient to support
+development of alternative porcelains.  Developers of such porcelains
+might start by reading about gitlink:git-update-index[1] and
+gitlink:git-read-tree[1].
+
+We divide the low-level commands into commands that manipulate objects (in
+the repository, index, and working tree), commands that interrogate and
+compare objects, and commands that move objects and references between
+repositories.
+
+Manipulation commands
+~~~~~~~~~~~~~~~~~~~~~
+gitlink:git-apply[1]::
+	Reads a "diff -up1" or git generated patch file and
+	applies it to the working tree.
+
+gitlink:git-checkout-index[1]::
+	Copy files from the index to the working tree.
+
+gitlink:git-commit-tree[1]::
+	Creates a new commit object.
+
+gitlink:git-hash-object[1]::
+	Computes the object ID from a file.
+
+gitlink:git-index-pack[1]::
+	Build pack idx file for an existing packed archive.
+
+gitlink:git-init-db[1]::
+	Creates an empty git object database, or reinitialize an
+	existing one.
+
+gitlink:git-merge-index[1]::
+	Runs a merge for files needing merging.
+
+gitlink:git-mktag[1]::
+	Creates a tag object.
+
+gitlink:git-mktree[1]::
+	Build a tree-object from ls-tree formatted text.
+
+gitlink:git-pack-objects[1]::
+	Creates a packed archive of objects.
+
+gitlink:git-prune-packed[1]::
+	Remove extra objects that are already in pack files.
+
+gitlink:git-read-tree[1]::
+	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]::
+	Registers files in the working tree to the index.
+
+gitlink:git-write-tree[1]::
+	Creates a tree from the index.
+
+
+Interrogation commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+gitlink:git-cat-file[1]::
+	Provide content or type/size information for repository objects.
+
+gitlink:git-describe[1]::
+	Show the most recent tag that is reachable from a commit.
+
+gitlink:git-diff-index[1]::
+	Compares content and mode of blobs between the index and repository.
+
+gitlink:git-diff-files[1]::
+	Compares files in the working tree and the index.
+
+gitlink:git-diff-stages[1]::
+	Compares two "merge stages" in the index.
+
+gitlink:git-diff-tree[1]::
+	Compares the content and mode of blobs found via two tree objects.
+
+gitlink:git-for-each-ref[1]::
+	Output information on each ref.
+
+gitlink:git-fsck-objects[1]::
+	Verifies the connectivity and validity of the objects in the database.
+
+gitlink:git-ls-files[1]::
+	Information about files in the index and the working tree.
+
+gitlink:git-ls-tree[1]::
+	Displays a tree object in human readable form.
+
+gitlink:git-merge-base[1]::
+	Finds as good common ancestors as possible for a merge.
+
+gitlink:git-name-rev[1]::
+	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.
+
+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 object.
+
+gitlink:git-unpack-file[1]::
+	Creates a temporary file with a blob's contents.
+
+gitlink:git-var[1]::
+	Displays a git logical variable.
+
+gitlink:git-verify-pack[1]::
+	Validates packed git archive files.
+
+In general, the interrogate commands do not touch the files in
+the working tree.
+
+
+Synching repositories
+~~~~~~~~~~~~~~~~~~~~~
+
+gitlink:git-fetch-pack[1]::
+	Updates from a remote repository (engine for ssh and
+	local transport).
+
+gitlink:git-http-fetch[1]::
+	Downloads a remote git repository via HTTP by walking
+	commit chain.
+
+gitlink:git-local-fetch[1]::
+	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 (engine for ssh and local
+	transport).
+
+gitlink:git-receive-pack[1]::
+	Invoked by 'git-send-pack' to receive what is pushed to it.
+
+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 by
+	walking commit chain.
+
+gitlink:git-ssh-upload[1]::
+	Helper "server-side" program used by git-ssh-fetch.
+
+gitlink:git-update-server-info[1]::
+	Updates auxiliary information on a dumb server to help
+	clients discover references and packs on it.
+
+gitlink:git-upload-archive[1]::
+	Invoked by 'git-archive' to send a generated archive.
+
+gitlink:git-upload-pack[1]::
+	Invoked by 'git-fetch-pack' to push
+	what are asked for.
+
+
 Configuration Mechanism
 -----------------------