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

[Junio C Hamano <gitster@pobox.com>]

Marc Branchaud <marcnarc@xiplink.com> 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 ;-)

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

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.