Re: [PATCH 1/2] fetch: add missing documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Sep 24, 2013, 05:57 UTC
Message-ID: <CAMP44s3QfkvXjgmhWPXN7qonbEPpvJFyVm82EBOMSjX7ng3OQg@mail.gmail.com>
In-Reply-To: <20130924054053.GA6192@sigill.intra.peff.net>

On Tue, Sep 24, 2013 at 12:40 AM, Jeff King <peff@peff.net> wrote:

Show 26 quoted lines

> On Tue, Sep 24, 2013 at 12:36:38AM -0500, Felipe Contreras wrote:
>
>> > Yeah, it's not a term we use elsewhere, so it's not great. Probably
>> > "default remote" would be better, or even just say "branch.*.remote for
>> > the current branch" or something.
>>
>> Yeah, general users don't know what you are talking about when you say that.
>
> Right, I understand your complaint and agree that those terms are
> potentially confusing.
>
>> > I dunno. I don't particularly like any of those, but I really dislike
>> > the imprecision of "upstream branch" in this case.
>>
>> For most users it's the remote configured by:
>>
>> % git branch --set-upstream-to foo
>> % git checkout -b foo origin/foo
>> % git checkout -t -b foo bar
>>
>> So when they read "upstream branch" they know from where it got configured.
>
> Yes, but it is also wrong, in the sense that the upstream branch is
> unrelated. You are giving breadcrumbs to users who know "upstream
> branch" as a concept and nothing else, but you are misleading users who
> know that branch.*.remote exists.

No, I'm not. The users that know branch.*.remote exists know why it exists. The part where it is explained, 'git config --help', is perfectly clear: "When on branch <name>, it tells 'git fetch' and 'git push' which remote to fetch from/push to.". So what does branch.<name>.remote does, if not precisely what the documentation says?

This is not a rhetorical question, I'm actually expecting you to answer, if a user knows that branch.<name>.remote exists, how would the above confuse him?

> I was hoping you might suggest something that can help both users by
> being both precise and giving the appropriate breadcrumbs.

This is documentation for a Git porcelain command, branch.<name>.remote is an implementation detail, and it's irrelevant in the documentation at this level.

-- 
Felipe Contreras