[PATCH/RFC v2 resend] Documentation: flesh out “git pull” description

[Jonathan Nieder <jrnieder@gmail.com>]

The current description in the pull man page does not say much more
than that “git pull” is fetch + merge.  Though that is all a person
needs to know in the end, it would be useful to summarize a bit about
what those commands do for new readers.

Most of this description is taken from the “git merge” docs.

Now that we explain how to back out of a failed merge (reset --merge),
we can tone down the warning against that a bit.

Except, as Thomas noticed, there’s a risk with that because people
might read this version of the manpage online and then conclude that
it is safe to try a merge with uncommitted changes, only to find that
their “git reset” doesn't support --merge yet.  Or worse, verify that
their git-reset has --merge by a quick test (1b5b465 is in 1.6.2) but
then find that it does not help with backing out of a merge (e11d7b5
is only in 1.7.0!).  For the master copy of the documentation on
kernel.org (but not the historical versions) we should keep the
warning.

So abuse the staledocs[] macro (currently used to suppress the Note in
git.html about previous versions of documentation) to distinguish
these cases.

Noticed-by: Geoff Russell <geoffrey.russell@gmail.com>
Improved-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Improved-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
[misspelled an email address.  sorry for the noise!]

Changes since v1[1]:

 - remove a stray article
 - stop lying in the synopsis
 - use an ifdef to allow the warning about situations that may be difficult to
   recover from to be kept when building the "universal" docs that should
   apply to git versions before 1.7, too.

Junio: ideally for this to work, git-pull.html would need to get the
same special treatment as git.html gets.  Does that seem doable?  Is
Meta/dodoc.sh still the script to do it?

[1] http://thread.gmane.org/gmane.comp.version-control.git/151799/focus=151801

 Documentation/git-pull.txt |   70 +++++++++++++++++++++++++++++++++++++-------
 1 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10..54e9619 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,77 @@ git-pull - Fetch from and merge with another repository or a local branch
 
 SYNOPSIS
 --------
-'git pull' <options> <repository> <refspec>...
+'git pull' [options] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
 -----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
 
-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.
+Incorporates changes from a remote repository into the current
+branch.  In its default mode, `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
 
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1].  <refspec> can name an
+arbitrary remote ref (for example, the name of a tag) or even
+a collection of refs with corresponding remote tracking branches
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
+the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+          A---B---C master on origin
+         /
+    D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `master` (i.e., `E`)
+until its current commit (`C`) on top of `master` and record the
+result in a new commit along with the names of the two parent commits
+and a log message from the user describing the changes.
+
+------------
+          A---B---C remotes/origin/master
+         /         \
+    D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+ifndef::stalenotes[]
+To cancel a conflicting merge, use `git reset --merge`.
+endif::stalenotes[]
+ifdef::stalenotes[]
+
+In git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`.  *Warning*: In older versions of git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+in a state that may be hard to back out of in the case of a conflict.
+endif::stalenotes[]
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
 
 OPTIONS
 -------
 
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
-- 
1.7.2.1.544.ga752d.dirty