Re: [PATCH] submodule documentation: Reorder introductory paragraphs

From: Junio C Hamano <gitster@pobox.com>
Date: May 22, 2015, 17:26 UTC
Message-ID: <xmqqvbfked6u.fsf@gitster.dls.corp.google.com>
In-Reply-To: <CAGZ79kYiG9=px3P+k1shqvt8ouXmfJjeKgCarj6KEQy08WAmjg@mail.gmail.com>

Stefan Beller <sbeller@google.com> writes:

Show 20 quoted lines

> On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Stefan Beller <sbeller@google.com> writes:
>>
>>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> wrote:
>>>>> +Submodules are not to be confused with remotes, which are meant
>>>>> +mainly for branches of the same project;
>>>>
>>>> This use of 'branches' didn't work for me. "remotes are meant mainly for
>>>> branches of the same project" ?
>>
>> The "branch" in the original is used in a much wider sense than
>> usual branch (i.e. ref/heads/ thing you have locally); it refers to
>> forks of the same project but with a bit of twist.  When you say
>> repository A is a fork of the same project as my local repository,
>> you would give an impression that A is not the authoritative copy of
>> the project.  But you can say my repository and that repository A
>> are branches of the same project, you give zero information as to
>> A's authoritativeness.
>
> While this is correct, I think it is also confusing, because...

Oh, no question about it. In modern Git parlance, it confuses by conflating 'branch' (which is local ref/heads/ thing) with something entirely different. I wasn't saying "'branch' is correct and we should keep the description that way".

If you dig ancient list archives, you see Linus and I using 'branch' to mean "your copy of the project" quite often, and that is likely where the above phrase originated. It was one of those "explaining historical background", nothing more.

I probably should start prefixing all my "explaining historical background" sentences as such.

Show 12 quoted lines

>> I do not think this is a great improvement.  You now conflated
>> "repository" to mean "project" in the latter half of the sentence,
>> while you are trying to explain what a "remote repository" is.
>
> That's true.
>>
>> Your copy of git.git is not the same repository as mine; they have
>> different histories.  Both repositories are used to work on the same
>> project.  "submoules are not remotes, which are other repositories
>> of the same project", perhaps?
>
> That makes sense.

Thanks.