git-pull.txt: correct outdated example + link to specific 'git fetch' section

[phil-blain]

I was reading the git pull documentation and discovered an outdated example description.
While reading the git fetch documentation to confirm the behaviour described in
git pull was indeed wrong, I figured it would be easier to refer directly to the "Configured remote-tracking branches" section in git fetch from the git pull documentation,
just as in git fetch.

CC: Jeff King peff@peff.net, Marc Branchaud marcnarc@xiplink.com, Clemens Buchacher drizzd@gmx.net

[phil-blain]

/submit

[gitgitgadget-git]

Submitted as pull.751.git.git.1586101819.gitgitgadget@gmail.com

[gitgitgadget-git]

This branch is now known as pb/pull-fetch-doc.

[gitgitgadget-git]

This patch series was integrated into pu via 9f70b5d.

[gitgitgadget-git]

On the Git mailing list, Jeff King wrote (reply to this):

On Sun, Apr 05, 2020 at 03:50:18PM +0000, Philippe Blain via GitGitGadget wrote:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
> 
> The documentation for the `<refspec>` parameter in the `git fetch`
> documentation refers to the section "CONFIGURED REMOTE-TRACKING
> BRANCHES" in this same documentation page.
> 
> In the `git pull` documentation, let's also refer specifically to this
> section instead of just linking to the `git fetch` documentation.

Makes sense. One thought:

> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
> index 7d3a60f5b93..95ea8499029 100644
> --- a/Documentation/pull-fetch-param.txt
> +++ b/Documentation/pull-fetch-param.txt
> @@ -19,7 +19,8 @@ ifndef::git-pull[]
>  	(see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below).
>  endif::git-pull[]
>  ifdef::git-pull[]
> -	(see linkgit:git-fetch[1]).
> +	(see the section "CONFIGURED REMOTE-TRACKING BRANCHES"
> +	in linkgit:git-fetch[1]).
>  endif::git-pull[]

We can hyperlink directly to this section with the CRTB tag (as you can
see in the context above). But I guess we don't have a portable macro to
do so across different manpages. Assuming we'd need something like
linkgit to accomplish, it's best not to hold up this change waiting for
that.

-Peff

[gitgitgadget-git]

On the Git mailing list, Philippe Blain wrote (reply to this):

Hi Peff,

> Le 6 avr. 2020 à 16:19, Jeff King <peff@peff.net> a écrit :
> 
> One thought:
> 
>> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
>> index 7d3a60f5b93..95ea8499029 100644
>> --- a/Documentation/pull-fetch-param.txt
>> +++ b/Documentation/pull-fetch-param.txt
>> @@ -19,7 +19,8 @@ ifndef::git-pull[]
>> 	(see <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> below).
>> endif::git-pull[]
>> ifdef::git-pull[]
>> -	(see linkgit:git-fetch[1]).
>> +	(see the section "CONFIGURED REMOTE-TRACKING BRANCHES"
>> +	in linkgit:git-fetch[1]).
>> endif::git-pull[]
> 
> We can hyperlink directly to this section with the CRTB tag (as you can
> see in the context above). But I guess we don't have a portable macro to
> do so across different manpages. Assuming we'd need something like
> linkgit to accomplish, it's best not to hold up this change waiting for
> that.

I didn't know it was possible. I agree that cross-linking directly to a specific section would be
great, especially if it would work for the manpages, the HTML documentation as well as the website!

Philippe.

[gitgitgadget-git]

On the Git mailing list, Jeff King wrote (reply to this):

On Sun, Apr 05, 2020 at 03:50:19PM +0000, Philippe Blain via GitGitGadget wrote:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
> 
> Since f269048754 (fetch: opportunistically update tracking refs,
> 2013-05-11), the underlying `git fetch` in `git pull <remote> <branch>`
> updates the configured remote-tracking branch for <branch>.
> 
> However, an example in the 'Examples' section of the `git pull`
> documentation still states that this is not the case.
> 
> Correct the description of this example.

Yeah, I think the example just never got updated. Your patch looks good.

Another option would be to use a direct URL rather than a configured
remote, which really would just update FETCH_HEAD. But I don't think the
handling of remote-tracking branches is central to this example either
way, so your minimal change is better.

-Peff

[gitgitgadget-git]

This patch series was integrated into pu via d2a81ce.

[gitgitgadget-git]

This patch series was integrated into pu via 824219a.

[gitgitgadget-git]

This patch series was integrated into pu via 3846156.

[gitgitgadget-git]

This patch series was integrated into pu via b79cfff.

[gitgitgadget-git]

This patch series was integrated into pu via 558238d.

[gitgitgadget-git]

This patch series was integrated into pu via cfa5ce0.

[gitgitgadget-git]

This patch series was integrated into next via cf530f2.

[gitgitgadget-git]

This patch series was integrated into pu via 017ec20.

[gitgitgadget-git]

This patch series was integrated into pu via cd0ab36.

[gitgitgadget-git]

This patch series was integrated into pu via fdee8b1.

[gitgitgadget-git]

This patch series was integrated into next via fdee8b1.

[gitgitgadget-git]

This patch series was integrated into master via fdee8b1.

[gitgitgadget-git]

Closed via fdee8b1.