[PATCH] docs: Explain the purpose of fetch's and pull's <refspec> parameter.

[Marc Branchaud <marcnarc@xiplink.com>]

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/git-fetch.txt        |  4 ++--
 Documentation/pull-fetch-param.txt | 17 ++++++++++++++---
 2 files changed, 16 insertions(+), 5 deletions(-)

On 14-06-04 06:17 PM, Junio C Hamano wrote:
> 
> Perhaps
> 
>     ... `remote.<repository>.fetch` values are used as the refspecs,
>     i.e. they specify what refs to fetch and what local refs to
>     update.
> 
> or something?

In fact, I like that so much I think it should be *the* description of
the <refspec> parameter.  Much better than just jumping straight into
the syntax.

This patch applies atop your 8/9.  I feel strongly that some kind of
reference should accompany this description, and your new CONFIGURED
REMOTE-TRACKING BRANCHES section seems like a good one for the fetch
variant, but since pull's variant doesn't have that section I just
made it link to fetch's doc.

(Also, I'm not sure if "CRTB" is a good link ID for your new section.)

		M.

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 4a735ab..a4cafa3 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -49,8 +49,8 @@ include::pull-fetch-param.txt[]
 include::urls-remotes.txt[]
 
 
-CONFIGURED REMOTE-TRACKING BRANCHES
------------------------------------
+CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
+-------------------------------------------
 
 You would often interact with the same remote repository by
 regularly and repeatedly fetching from it.  In order to keep track
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 18cffc2..40304c6 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -12,9 +12,20 @@ ifndef::git-pull[]
 endif::git-pull[]
 
 <refspec>::
-	The format of a <refspec> parameter is an optional plus
-	`+`, followed by the source ref <src>, followed
-	by a colon `:`, followed by the destination ref <dst>.
+	Specifies which refs to fetch and which local refs to update.
+	<refspec> parameters are not normally specified on the command
+	line, but instead are read from `remote.<repository>.fetch`
+	configuration variables
+ifndef::git-pull[]
+	(see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below).
+endif::git-pull[]
+ifdef::git-pull[]
+	(see linkgit:git-fetch[1]).
+endif::git-pull[]
++
+The format of a <refspec> parameter is an optional plus
+`+`, followed by the source ref <src>, followed
+by a colon `:`, followed by the destination ref <dst>.
 +
 The remote ref that matches <src>
 is fetched, and if <dst> is not empty string, the local
-- 
2.0.0.dirty