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

Marc Branchaud [off-list ref] writes:

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.)

Nobody looks at these ids, hopefully ;-)

That is an improvement.  We should first say what it is and what it
is for before saying how you spell it and the above change is
exactly that.

+	<refspec> parameters are not normally specified on the command
+	line, but instead are read from `remote.<repository>.fetch`

I however am not sure if this is an improvement, especially the
"normally" part.  Those who respond to a git-pull-request output
might be fewer than those who send pull requests, but that does not
mean they are abnormal.

	The command line often omit <refspec> parameters when
	fetching or pulling from a remote you regularly interact
	with, in which case `remote.<repository>.fetch` values are
	used instead.

would be OK, though.

Later today I'll push out the series on 'pu' after amending them
with your comments so far.  It would be nice if you can reroll this
on top of the updated one ("git log --oneline --first-parent
master..pu" and find jc/fetch-pull-refmap in there).

Thanks.

Signed-off-by: Marc Branchaud <redacted>
---
 Documentation/git-fetch.txt        |  4 ++--
 Documentation/pull-fetch-param.txt | 18 ++++++++++++++----
 2 files changed, 16 insertions(+), 6 deletions(-)

On 14-06-05 06:12 PM, Junio C Hamano wrote:

quoted

+	<refspec> parameters are not normally specified on the command
+	line, but instead are read from `remote.<repository>.fetch`

I however am not sure if this is an improvement, especially the
"normally" part.  Those who respond to a git-pull-request output
might be fewer than those who send pull requests, but that does not
mean they are abnormal.

	The command line often omit <refspec> parameters when
	fetching or pulling from a remote you regularly interact
	with, in which case `remote.<repository>.fetch` values are
	used instead.

would be OK, though.

Later today I'll push out the series on 'pu' after amending them
with your comments so far.  It would be nice if you can reroll this
on top of the updated one ("git log --oneline --first-parent
master..pu" and find jc/fetch-pull-refmap in there).

Here's the reroll.  I used completely different phrasing but I think
I still captured the gist of what you said.

(Apologies for the delay -- I was looking for jc/fetch-pull-refmap on pu,
not jc/fetch-push-refmap on next!)

		M.

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 629a1cf..8deb614 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt

@@ -51,8 +51,8 @@ include::pull-fetch-param.txt[]
 include::urls-remotes.txt[]
 
 
-CONFIGURED REMOTE-TRACKING BRANCHES
------------------------------------
+CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
+-------------------------------------------
 
 You 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 4bff65b..1ebbf1d 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt

@@ -12,10 +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>.
-	The colon can be omitted when <dst> is empty.
+	Specifies which refs to fetch and which local refs to update.
+	When no <refspec>s appear on the command line, the refs to fetch
+	are read from `remote.<repository>.fetch` variables instead
+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 colon can be omitted when <dst> is empty.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
 it requests fetching everything up to the given tag.

-- 
2.0.0.dirty