[PATCH] submodule documentation: Reorder introductory paragraphs

[PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

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.
 
 COMMANDS
 --------
-- 
2.4.0.194.gc518059

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Heiko Voigt]

On Wed, May 20, 2015 at 04:11:57PM -0700, Stefan Beller wrote:
> 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>

Looks good to me.

Cheers Heiko

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Junio C Hamano]

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

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

On Thu, May 21, 2015 at 10:24 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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, ...

I agree, maybe we should reword the paragraphs themselves as well.

    Submodules allow you to keep another Git repository in a subdirectory
    of your repository. The other repository has its own history, which does not
    interfere with the history of the current repository. This can be used to
    have external dependencies such as libraries for example.

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

I agree.

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
> 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;

This use of 'branches' didn't work for me. "remotes 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.
>
--
Philip 

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

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.

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
> 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.
>

I like that better. I was going to check what the git glossary said a 
remote was, but the commute to work beckons...

Philip 

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Junio C Hamano]

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?

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

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.

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

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

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

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Philip Oakley]

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

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

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 

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

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

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
> 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!

Hi Stefan,
This was more of a case of "simply a full stop, 'cos I can't easily tell 
you why" ;-).  I've seen too many work situations (*) where colleagues 
just dig deeper when they should stop digging, hence the note. It may be 
that the style of reason could be changed. This is the final 
introductory paragraph and was being pushed down partly because of this 
problem (explaining things by saying what its not).

(*) The usual phrase in a report would be "A moments thought will show 
that ..." for those concepts that would take two pages to explain and 
would still be misunderstood by the unthinking folks.

That all said, if a nice well understood explanatory phrase can be found 
then I'm all for it.

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

I'd avoided mentioning that potential explanation mud-hole on the same 
basis that it would be hard.

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

[PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

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.

Additionally to reordering the paragraphs, they have been slightly
reworded.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

For now I used a part of Junios suggestion
    Submodules are not to be confused with remotes, which are other
    repositories of the same project;
    
I like the "are not to be confused" part, as they warn the reader
that there will be a paragraph not as concise but touching other
commands and topics.

 Documentation/git-submodule.txt | 50 ++++++++++++++++++-----------------------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2c25916..d126c86 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -25,22 +25,17 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Submodules allow foreign repositories to be embedded within
-a dedicated subdirectory of the source tree, always pointed
-at a particular commit.
+This command will inspect, update and manage submodules.
 
-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 allow you to keep another Git repository in a subdirectory
+of your repository. The other repository has its own history, which does not
+interfere with the history of the current repository. This can be used to
+have external dependencies such as libraries for example.
+
+When cloning or pulling a repository containing submodules however,
+these will not be checked out by default; the 'init' and 'update'
+subcommands will maintain submodules checked out and at
+appropriate revision in your working tree.
 
 Submodules are composed from a so-called `gitlink` tree entry
 in the main repository that refers to a particular commit object
@@ -51,19 +46,18 @@ 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.
-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;
-the 'init' and 'update' subcommands will maintain submodules
-checked out and at appropriate revision in your working tree.
-You can briefly inspect the up-to-date status of your submodules
-using the 'status' subcommand and get a detailed overview of the
-difference between the index and checkouts using the 'summary'
-subcommand.
-
+Submodules are not to be confused with remotes, which are other
+repositories 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.
 
 COMMANDS
 --------
-- 
2.4.1.233.g3f9b614.dirty

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
> 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.
>
> Additionally to reordering the paragraphs, they have been slightly
> reworded.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
> For now I used a part of Junios suggestion
>    Submodules are not to be confused with remotes, which are other
>    repositories of the same project;
>
> I like the "are not to be confused" part, as they warn the reader
> that there will be a paragraph not as concise but touching other
> commands and topics.
>
> Documentation/git-submodule.txt | 50 
> ++++++++++++++++++-----------------------
> 1 file changed, 22 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt 
> b/Documentation/git-submodule.txt
> index 2c25916..d126c86 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -25,22 +25,17 @@ SYNOPSIS
>
> DESCRIPTION
> -----------
> -Submodules allow foreign repositories to be embedded within
> -a dedicated subdirectory of the source tree, always pointed
> -at a particular commit.
> +This command will inspect, update and manage submodules.
>
> -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 allow you to keep another Git repository in a subdirectory
> +of your repository. The other repository has its own history, which 
> does not
> +interfere with the history of the current repository. This can be 
> used to
> +have external dependencies such as libraries for example.
> +
> +When cloning or pulling a repository containing submodules however,
> +these will not be checked out by default; the 'init' and 'update'
> +subcommands will maintain submodules checked out and at
> +appropriate revision in your working tree.
>
> Submodules are composed from a so-called `gitlink` tree entry
> in the main repository that refers to a particular commit object
> @@ -51,19 +46,18 @@ 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.
> -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;
> -the 'init' and 'update' subcommands will maintain submodules
> -checked out and at appropriate revision in your working tree.
> -You can briefly inspect the up-to-date status of your submodules
> -using the 'status' subcommand and get a detailed overview of the
> -difference between the index and checkouts using the 'summary'
> -subcommand.
> -
> +Submodules are not to be confused with remotes, which are other
> +repositories of the same project;

I said (22 May 2015 20:47):
"if a nice well understood explanatory phrase can be found " - I'm happy 
with yours. Many thanks

>                                        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.
>
> COMMANDS
> --------
> -- 
> 2.4.1.233.g3f9b614.dirty
>
> --
Philip 

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>  DESCRIPTION
>  -----------
> +This command will inspect, update and manage submodules.
>  
> +Submodules allow you to keep another Git repository in a subdirectory
> +of your repository. The other repository has its own history,...

The first line somehow bothered me, so I took a random sample of
commands I often use:

    git log
       Shows the commit logs.

    git show
       Shows one or more objects (blobs, trees, tags and commits).

    git commit
       Stores the current contents of the index in a new commit along with a
       log message from the user describing the changes.

    git diff
       Show changes between the working tree and the index or a tree, changes
       between the index and a tree, changes between two trees, changes
       between two blob objects, or changes between two files on disk.

    git push
       Updates remote refs using local refs, while sending objects necessary
       to complete the given refs.

I _think_ what bothered me was "This command" (drawing the reaction
"eh, what other command are you going to talk about in the help page
for this command?").  Perhaps

    Inspects, updates and manages submodules.

may match the style of other help pages better.

On the other hand, I probably would not have felt such a strong
"strangeness" if it were described like this:

    This command can help you inspect, update, and manage
    submodules.

I haven't analized it enough to say why it is, but I suspect it has
something to do with (my own) perception that "git submodule" is not
very essential to do any of these things (i.e. .gitmodules is a very
simple text file), but is primarily a helpful wrapper.

The description of "git config", on which I have a similar
perception, seem to match ;-)

    git config
       You can query/set/replace/unset options with this command.

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller]

On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>>  DESCRIPTION
>>  -----------
>> +This command will inspect, update and manage submodules.
>>
>> +Submodules allow you to keep another Git repository in a subdirectory
>> +of your repository. The other repository has its own history,...
>
> The first line somehow bothered me, so I took a random sample of
> commands I often use:
>
>     git log
>        Shows the commit logs.
>
>     git show
>        Shows one or more objects (blobs, trees, tags and commits).
>
>     git commit
>        Stores the current contents of the index in a new commit along with a
>        log message from the user describing the changes.
>
>     git diff
>        Show changes between the working tree and the index or a tree, changes
>        between the index and a tree, changes between two trees, changes
>        between two blob objects, or changes between two files on disk.
>
>     git push
>        Updates remote refs using local refs, while sending objects necessary
>        to complete the given refs.
>
> I _think_ what bothered me was "This command" (drawing the reaction
> "eh, what other command are you going to talk about in the help page
> for this command?").  Perhaps
>
>     Inspects, updates and manages submodules.
>
> may match the style of other help pages better.

Sounds much better than my patch.

>
> On the other hand, I probably would not have felt such a strong
> "strangeness" if it were described like this:
>
>     This command can help you inspect, update, and manage
>     submodules.
>
> I haven't analized it enough to say why it is, but I suspect it has
> something to do with (my own) perception that "git submodule" is not
> very essential to do any of these things (i.e. .gitmodules is a very
> simple text file), but is primarily a helpful wrapper.

My perception is that the submodule man page similar to the subtree
man page tries to explain an underlying concept as well. The other man
pages you quoted don't do that as the concepts are explained elsewhere(?)

As a side note: In the Gerrit test suite I use the JGit implementation of
the config command to write out .gitmodules files. So maybe `git submodule`
can be understood as a specialized form of `git config`.

>
> The description of "git config", on which I have a similar
> perception, seem to match ;-)
>
>     git config
>        You can query/set/replace/unset options with this command.
>

Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Heiko Voigt]

On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote:
> On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:
> > Stefan Beller <sbeller@google.com> writes:
> > On the other hand, I probably would not have felt such a strong
> > "strangeness" if it were described like this:
> >
> >     This command can help you inspect, update, and manage
> >     submodules.
> >
> > I haven't analized it enough to say why it is, but I suspect it has
> > something to do with (my own) perception that "git submodule" is not
> > very essential to do any of these things (i.e. .gitmodules is a very
> > simple text file), but is primarily a helpful wrapper.
> 
> My perception is that the submodule man page similar to the subtree
> man page tries to explain an underlying concept as well. The other man
> pages you quoted don't do that as the concepts are explained elsewhere(?)
> 
> As a side note: In the Gerrit test suite I use the JGit implementation of
> the config command to write out .gitmodules files. So maybe `git submodule`
> can be understood as a specialized form of `git config`.

I do not agree here. That view is too limited. Since in the case of e.g. 'git
submodule add‘ it does not only change the .gitmodules file but adds a gitlink
entry to the index, moves the database into .git/modules, ... .

And even though it is currently not doing much more it might in the
future. E.g. it might make sense to add a 'git submodule gc' command
which allows the user to purge unused submodule databases from the
.git/modules directory.

So I would say it is: "a helper" or "a tool" for submodules. Nothing less
nothing more. But on the other hand the same is true for other porcelain
commands like e.g. 'git commit'. If you take a look at gitcore-tutorial
you could also describe it as a wrapper for write-tree, commit-tree and
update-ref to create a commit. Yet the man page says: "Record changes to
the repository".

So I am not sure where to draw the line between wrapper and essential
command. As a user I would see it as quite essential since for adding a
submodule I would need to remember a couple of things:

  * clone the database into .git/modules
  * create the gitlink file
  * checkout the files to the desired directory
  * add the url to the .gitmodules file

So why not go with Junios first suggestion and lets drop the "This
command can help you..." and say: "Inspect, update and manage
submodules".

Cheers Heiko