Documentation: git-fetch/pull updates.

We do not accept multiple <refspecs> on one Pull:/Push: line
right now (we could lift this tentative workaround for the
broken refnames), but we have always accepted multiple such
lines, so use that form in the examples and discussion.

Also explicitly mention that Octopus is made only with an
explicit command line request and never from Pull: lines.

Add a couple of cross references.

Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 71693650c4194514f62dd5d8524b446dd8641805..73f8a99ffe6e3d6b09377226d3fb83fbf6494994 100644 (file)
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -37,6 +37,11 @@ include::pull-fetch-param.txt[]
        update the index and working directory, so use it with care.
 
 
+SEE ALSO
+--------
+gitlink:git-pull[1]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index da6537d9110ced743c42cba99111923a0753eb6d..3e058db996cbb1200fc304b3a090cbd4e13fce80 100644 (file)
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -37,7 +37,7 @@ include::merge-pull-opts.txt[]
 
 SEE ALSO
 --------
-gitlink:git-fmt-merge-msg[1]
+gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
 
 
 Author

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 5a11da1f7424a4f2ff1375b6cb8d4f11440c47a3..ec10a2f409a6cd3d7340cfc934c53ccd5a00f5f0 100644 (file)
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -141,6 +141,11 @@ merge the remote `origin` head into the current,
 local `master` branch.
 
 
+SEE ALSO
+--------
+gitlink:git-fetch[1], gitlink:git-merge[1]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 2a7131874be370579f2f1ef4a72074b5d8b86141..57e9ddf0d605e5536ce21901494c0058ef4ce857 100644 (file)
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -17,12 +17,12 @@ file in `$GIT_DIR/remotes` directory can be given; the
 named file should be in the following format:
 +
        URL: one of the above URL format
-       Push: <refspec>...
-       Pull: <refspec>...
+       Push: <refspec>
+       Pull: <refspec>
 +
 When such a short-hand is specified in place of
 <repository> without <refspec> parameters on the command
-line, <refspec>... specified on `Push:` lines or `Pull:`
+line, <refspec> specified on `Push:` lines or `Pull:`
 lines are used for `git-push` and `git-fetch`/`git-pull`,
 respectively.  Multiple `Push:` and and `Pull:` lines may
 be specified for additional branch mappings.
@@ -91,6 +91,22 @@ remote `master` branch to a local `origin` branch, which
 is then merged to a local development branch, again typically
 named `master`.
 +
+[NOTE]
+There is a difference between listing multiple <refspec>
+directly on `git-pull` command line and having multiple
+`Pull:` <refspec> lines for a <repository> and running
+`git-pull` command without any explicit <refspec> parameters.
+<refspec> listed explicitly on the command line are always
+merged into the current branch after fetching.  In other words,
+if you list more than one remote refs, you would be making
+an Octopus.  While `git-pull` run without any explicit <refspec>
+parameter takes default <refspec>s from `Pull:` lines, it
+merges only the first <refspec> found into the current branch,
+after fetching all the remote refs.  This is because making an
+Octopus from remote refs is rarely done, while keeping track
+of multiple remote heads in one-go by fetching more than one
+is often useful.
++
 Some short-cut notations are also supported.
 +
 * For backward compatibility, `tag` is almost ignored;