Re: [PATCH] submodule documentation: Reorder introductory paragraphs

From: Stefan Beller <sbeller@google.com>
Date: May 22, 2015, 17:05 UTC
Message-ID: <CAGZ79kYiG9=px3P+k1shqvt8ouXmfJjeKgCarj6KEQy08WAmjg@mail.gmail.com>
In-Reply-To: <xmqqwq00fzlv.fsf@gitster.dls.corp.google.com>

On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 17 quoted lines

> 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 'branch' is a command which deals with local branches only in my perception To deal with remote branches you need to use the commands {remote, fetch, pull}.

So when someone mentions "branch" I need to think of local operations in one repository and not on different distributed histories.

Show 7 quoted lines

>
>>     Submodules should not be confused with remote repositories, which are
>>     meant to track the same repository, just at another location; ...
>
> 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.

Show 5 quoted lines

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