Re: [PATCH] submodule documentation: Reorder introductory paragraphs

> On Fri, May 22, 2015 at 10:35 AM, Philip Oakley <philipoakley@iee.org> 
> wrote:
>> From: "Stefan Beller" <sbeller@google.com>
>>>
>>> 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 
>>> '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.
>>>
>>
>> If we are having difficulties defining a "remote" here (its not 
>> defined in
>> gitglossary.txt anyway),
>
> Now that we have a discussion on what remotes are, I'll send a patch 
> for that
> as well.
>
>> why not simply put a full stop (period) after the
>> "Submodules are not to be confused with remotes.", and bypass the 
>> problem,
>> avoiding digging the hole deeper.
>
> I think we should dig deeper and point out the differences as it may
> not be clear what
> the differences are for new comers. Not digging deeper sounds to me 
> like saying
>
>    'git frotz' is not to be confused with 'git bar' FULL STOP AND I
> WONT TELL YOU WHY!

>
> which is not helpful. (Why is the documentation pointing out there is
> a difference to
> that other command/concept, but not saying what is different?)
>
>>
>>>>
>>>>>     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.
>>>
>>>>
>>>> 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.
>>>
>>
>> If maybe that the feature we should pick on is the common root of the
>> development between the local and remote repository, and quite 
>> distinct for
>> the submodule. This allows remotes to be on the same machine, as well 
>> as
>> distant machines and server.
>
> I don't think this is actually true for all remotes. Think of shallow 
> clones
> (they have no root or a different root) or even subtrees which are 
> pulled
> in via a remotes?

>
> The main thing about remotes is "not being here" (as in "part of this
> repository". As you point out it can be nearby in the local fs or even 
> on
> another machine, or in the cloud)
>
>>
>> It is I believe technically possible to have a submodule which is its 
>> own
>> super project, with and without recursion, but would be very 
>> atypical, and
>> would belong in the 'don't do that' category
>