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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Tue, Sep 24, 2013 at 1:10 AM, Jeff King <peff@xxxxxxxx> wrote:
> On Tue, Sep 24, 2013 at 12:57:36AM -0500, Felipe Contreras wrote:
>
>> 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 do not know if by "above" you mean the part of git-config.1 you quoted
> above, or the text you are proposing to put into git-fetch.1.
>
> If the former, then I do not think it is confusing at all. The existing
> text explains exactly what is going on.
>
> If the latter, then my concern is that the term "upstream branch"
> implies implies that "git fetch" depends on branch.*.merge, but it does
> not.

That does not answer the question. The user knows branch.<name>.remote
exists, the user reads "When no remote is specified, by the default
the upstream branch configured for the current branch will be used",
how would that confuse him?

Since you are not able to answer, I will answer for you; the user
would not be confused, because the user knows the upstream tracking
branch is composed by branch.<name>.remote+merge, if the user doesn't
know that (very highly unlikely), the user can ignore the whole text,
and the concept of "upstream branch" (which any user familiar with
branch.<name>.remote would know anyway).

So, to this hypothetical non-existent user, such text would read "When
no remote is specified, by the default whaa-whaa-whaa will be used".
Doesn't matter what whaa-whaa-whaa is, the user knows
branch.<name>.remote will be used, because that's what the
documentation for branch.<name>.remote says.

But let's imagine an even more hypothetical user who does actually
wonder what would take priority, whaa-whaa-whaa, or
branch.<name>.remote. Well, clearly, if he hasn't specifically set
whaa-whaa-whaa, then his beloved branch.<name>.remote would be used,
but wait, there's more, he wonders if whaa-whaa-whaa is actually set
somehow, without him knowing, well then there are three options: 1)
whaa-whaa-whaa takes priority, 2) branch.<name>.remote takes priority
3) they are the same. Of these only 1) is a problem.

But this extremely extremely hypothetical user can just go ahead and
google "git upstream branch", and quickly find it indeed is
branch.<name>.remote+merge.

So... Where is the problem?

>> > 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.
>
> I don't think it is the end of the world if we say "upstream branch". I
> was hoping to find a term that could be both friendly and accurate.
>
> And failing that, I hoped you might say "I see what you are saying, but
> I cannot think of a term that is more precise that does not sacrifice
> friendliness". But as I seem incapable of even communicating the issue
> to you, I'm giving up. It is not worth wasting more time on it.

And I was hoping you wouldn't use rhetorical warfare and label things
as "inaccurate", "imprecise", "breadcrumbs".

At this porcelain level, branch.<name>.remote does not exist, so
"upstream branch" is accurate. Period.

-- 
Felipe Contreras
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]