patchsubmodule documentation: Reorder introductory paragraphs

> It's better to start the man page with a description of what submodules
> actually are instead of saying what they are not.
> 
> Reorder the paragraphs such that
> the first short paragraph introduces the submodule concept,
> the second paragraph highlights the usage of the submodule command,
> the third paragraph giving background information,
> and finally the fourth paragraph discusing alternatives such
> as subtrees and remotes, which we don't want to be confused with.
> 
> This ordering deepens the knowledge on submodules with each paragraph.
> First the basic questions like "How/what" will be answered, while the
> underlying concepts will be taught at a later time.
> 
> Making sure it is not confused with subtrees and remotes is not really
> enhancing knowledge of submodules itself, but rather painting the big
> picture of git concepts, so you could also argue to have it as the second
> paragraph. Personally I think this may confuse readers, specially newcomers
> though.
> 
> Signed-off-by: Stefan Beller <sbeller@google.com>

> Reorder the paragraphs such that
> the first short paragraph introduces the submodule concept,
> the second paragraph highlights the usage of the submodule command,
> the third paragraph giving background information,
> and finally the fourth paragraph discusing alternatives such
> as subtrees and remotes, which we don't want to be confused with.
>
> This ordering deepens the knowledge on submodules with each paragraph.
> First the basic questions like "How/what" will be answered, while the
> underlying concepts will be taught at a later time.

> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 2c25916..6c38c0d 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -25,35 +25,12 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Submodules allow foreign repositories to be embedded within
> -a dedicated subdirectory of the source tree, always pointed
> -at a particular commit.
> +Submodules allow other repositories to be embedded within
> +a dedicated subdirectory of the source tree pointing
> +at a particular commit in the other repository.

> -This command will manage the tree entries and contents of the
> -gitmodules file for you, as well as inspect the status of your
> -submodules and update them.
> +This command will manage the submodules for you, as well as
> +inspect the status of your submodules and update them.

> Stefan Beller <sbeller@google.com> writes:
>
>> Reorder the paragraphs such that
>> the first short paragraph introduces the submodule concept,
>> the second paragraph highlights the usage of the submodule command,
>> the third paragraph giving background information,
>> and finally the fourth paragraph discusing alternatives such
>> as subtrees and remotes, which we don't want to be confused with.
>>
>> This ordering deepens the knowledge on submodules with each paragraph.
>> First the basic questions like "How/what" will be answered, while the
>> underlying concepts will be taught at a later time.
>
> Sounds good.
>
>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
>> index 2c25916..6c38c0d 100644
>> --- a/Documentation/git-submodule.txt
>> +++ b/Documentation/git-submodule.txt
>> @@ -25,35 +25,12 @@ SYNOPSIS
>>
>>  DESCRIPTION
>>  -----------
>> -Submodules allow foreign repositories to be embedded within
>> -a dedicated subdirectory of the source tree, always pointed
>> -at a particular commit.
>> +Submodules allow other repositories to be embedded within
>> +a dedicated subdirectory of the source tree pointing
>> +at a particular commit in the other repository.
>
> Not a new problem, but I can misread this as if it requires the
> top-level superproject to have one single dedicated directory D to
> house all the foreign projects under it, D/project1, D/project2, ...

>
>> -This command will manage the tree entries and contents of the
>> -gitmodules file for you, as well as inspect the status of your
>> -submodules and update them.
>> +This command will manage the submodules for you, as well as
>> +inspect the status of your submodules and update them.
>
> Not a new problem, but does the command really "manage them for
> you"?  I view it more like "You can use this command to manage,
> inspect and update the submodules".

> It's better to start the man page with a description of what 
> submodules
> actually are instead of saying what they are not.
>
> Reorder the paragraphs such that
> the first short paragraph introduces the submodule concept,
> the second paragraph highlights the usage of the submodule command,
> the third paragraph giving background information,
> and finally the fourth paragraph discusing alternatives such
> as subtrees and remotes, which we don't want to be confused with.
>
> This ordering deepens the knowledge on submodules with each paragraph.
> First the basic questions like "How/what" will be answered, while the
> underlying concepts will be taught at a later time.
>
> Making sure it is not confused with subtrees and remotes is not really
> enhancing knowledge of submodules itself, but rather painting the big
> picture of git concepts, so you could also argue to have it as the 
> second
> paragraph. Personally I think this may confuse readers, specially 
> newcomers
> though.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
> Documentation/git-submodule.txt | 54 
> ++++++++++++++++++++---------------------
> 1 file changed, 26 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt 
> b/Documentation/git-submodule.txt
> index 2c25916..6c38c0d 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -25,35 +25,12 @@ SYNOPSIS
>
> DESCRIPTION
> -----------
> -Submodules allow foreign repositories to be embedded within
> -a dedicated subdirectory of the source tree, always pointed
> -at a particular commit.
> +Submodules allow other repositories to be embedded within
> +a dedicated subdirectory of the source tree pointing
> +at a particular commit in the other repository.
>
> -They are not to be confused with remotes, which are meant mainly
> -for branches of the same project; submodules are meant for
> -different projects you would like to make part of your source tree,
> -while the history of the two projects still stays completely
> -independent and you cannot modify the contents of the submodule
> -from within the main project.
> -If you want to merge the project histories and want to treat the
> -aggregated whole as a single project from then on, you may want to
> -add a remote for the other project and use the 'subtree' merge 
> strategy,
> -instead of treating the other project as a submodule. Directories
> -that come from both projects can be cloned and checked out as a whole
> -if you choose to go that route.
> -
> -Submodules are composed from a so-called `gitlink` tree entry
> -in the main repository that refers to a particular commit object
> -within the inner repository that is completely separate.
> -A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
> -root of the source tree assigns a logical name to the submodule and
> -describes the default URL the submodule shall be cloned from.
> -The logical name can be used for overriding this URL within your
> -local repository configuration (see 'submodule init').
> -
> -This command will manage the tree entries and contents of the
> -gitmodules file for you, as well as inspect the status of your
> -submodules and update them.
> +This command will manage the submodules for you, as well as
> +inspect the status of your submodules and update them.
> When adding a new submodule to the tree, the 'add' subcommand
> is to be used.  However, when pulling a tree containing submodules,
> these will not be checked out by default;
> @@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed 
> overview of the
> difference between the index and checkouts using the 'summary'
> subcommand.
>
> +Submodules are composed from a so-called `gitlink` tree entry
> +in the main repository that refers to a particular commit object
> +within the inner repository that is completely separate.
> +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
> +root of the source tree assigns a logical name to the submodule and
> +describes the default URL the submodule shall be cloned from.
> +The logical name can be used for overriding this URL within your
> +local repository configuration (see 'submodule init').
> +
> +Submodules are not to be confused with remotes, which are meant
> +mainly for branches of the same project;

>  submodules are meant for
> +different projects you would like to make part of your source tree,
> +while the history of the two projects still stays completely
> +independent and you cannot modify the contents of the submodule
> +from within the main project.
> +If you want to merge the project histories and want to treat the
> +aggregated whole as a single project from then on, you may want to
> +add a remote for the other project and use the 'subtree' merge 
> strategy,
> +instead of treating the other project as a submodule. Directories
> +that come from both projects can be cloned and checked out as a whole
> +if you choose to go that route.
>

>> +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" ?
>

> 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" ?
>>
>
> Maybe
>
>    Submodules should not be confused with remote repositories, which 
> are
>    meant to track the same repository, just at another location; ...
>
> ? Though I'm not yet completely happy with that either.
>

> 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" ?

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

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

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

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

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

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

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

> 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),

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

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