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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 5, 2014, 22:12 UTC
Message-ID: <xmqq61kfroow.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1401982803-22346-1-git-send-email-marcnarc@xiplink.com>

Marc Branchaud <marcnarc@xiplink.com> writes:

Show 7 quoted lines

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

Show 12 quoted lines

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