[PATCH] glossary: add "remote" and "submodule"

[PATCH] glossary: add "remote" and "submodule"

[Stefan Beller]

Noticed-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/glossary-content.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index bf383c2..e303135 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -469,6 +469,11 @@ The most notable example is `HEAD`.
 	<<def_push,push>> to describe the mapping between remote
 	<<def_ref,ref>> and local ref.
 
+[[def_remote]]remote repository::
+	A <<def_repository,repository>> which is used to track the same
+	project but resides somewhere else. To communicate with remotes,
+	see <<def_fetch,fetch>> or <<def_push,push>>.
+
 [[def_remote_tracking_branch]]remote-tracking branch::
 	A <<def_ref,ref>> that is used to follow changes from another
 	<<def_repository,repository>>. It typically looks like
@@ -515,6 +520,11 @@ The most notable example is `HEAD`.
 	is created by giving the `--depth` option to linkgit:git-clone[1], and
 	its history can be later deepened with linkgit:git-fetch[1].
 
+[[def_submodule]]submodule::
+	A <<def_repository,repository>> inside another repository. The two
+	repositories have different history, though the outer repository
+	knows the commit of the inner repository.
+
 [[def_symref]]symref::
 	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
 	id itself, it is of the format 'ref: refs/some/thing' and when
-- 
2.4.1.345.gab207b6.dirty

Re: [PATCH] glossary: add "remote" and "submodule"

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Noticed-by: Philip Oakley <philipoakley@iee.org>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  Documentation/glossary-content.txt | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index bf383c2..e303135 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.
>  	<<def_push,push>> to describe the mapping between remote
>  	<<def_ref,ref>> and local ref.
>  
> +[[def_remote]]remote repository::
> +	A <<def_repository,repository>> which is used to track the same
> +	project but resides somewhere else. To communicate with remotes,
> +	see <<def_fetch,fetch>> or <<def_push,push>>.
> +

OK.

> @@ -515,6 +520,11 @@ The most notable example is `HEAD`.
>  	is created by giving the `--depth` option to linkgit:git-clone[1], and
>  	its history can be later deepened with linkgit:git-fetch[1].
>  
> +[[def_submodule]]submodule::
> +	A <<def_repository,repository>> inside another repository. The two
> +	repositories have different history, though the outer repository
> +	knows the commit of the inner repository.

I'd stress that they are not just different histories (as the
'master' and the 'maint' branches of my project has different
histories) but they are separate projects.  Perhaps like this?

       A repository that holds the history of a separate project
       inside another repository (the latter of which is called
       superproject).  The containing superproject knows about the
       names of (but does not hold copies of) commit objects of the
       contained submodules.

It is not like that it is strange or unintuitive that the
superproject knows about some commits in its submodule.  "X, though
Y" however makes it sound as if Y is true "despite X".  I do not
think there is any "despite" here.

Re: [PATCH] glossary: add "remote" and "submodule"

[Stefan Beller]

On Wed, May 27, 2015 at 3:29 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> Noticed-by: Philip Oakley <philipoakley@iee.org>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>  Documentation/glossary-content.txt | 10 ++++++++++
>>  1 file changed, 10 insertions(+)
>>
>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
>> index bf383c2..e303135 100644
>> --- a/Documentation/glossary-content.txt
>> +++ b/Documentation/glossary-content.txt
>> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.
>>       <<def_push,push>> to describe the mapping between remote
>>       <<def_ref,ref>> and local ref.
>>
>> +[[def_remote]]remote repository::
>> +     A <<def_repository,repository>> which is used to track the same
>> +     project but resides somewhere else. To communicate with remotes,
>> +     see <<def_fetch,fetch>> or <<def_push,push>>.
>> +
>
> OK.
>
>> @@ -515,6 +520,11 @@ The most notable example is `HEAD`.
>>       is created by giving the `--depth` option to linkgit:git-clone[1], and
>>       its history can be later deepened with linkgit:git-fetch[1].
>>
>> +[[def_submodule]]submodule::
>> +     A <<def_repository,repository>> inside another repository. The two
>> +     repositories have different history, though the outer repository
>> +     knows the commit of the inner repository.
>
> I'd stress that they are not just different histories (as the
> 'master' and the 'maint' branches of my project has different
> histories) but they are separate projects.  Perhaps like this?

This is a very subtle distinction IMHO, as both master and maint
"are the same project". Looking from enough distance, it's just the
git project without the fine detail of what makes these 2 histories different.
I tried coming up with a short paragraph, which may explain my choice
of words. But correctness trumps brevity indeed.

>
>        A repository that holds the history of a separate project
>        inside another repository (the latter of which is called
>        superproject).

This is better than what I proposed, but confusing. When naming
a project a submodule, my mental standpoint is the superproject.
("This project has the submodule foo and bar"). But In your description
the superproject is called "another repository".

>        The containing superproject knows about the
>        names of (but does not hold copies of) commit objects of the
>        contained submodules.

That makes sense to point out here. Though should we also introduce
"superproject" now?

>
> It is not like that it is strange or unintuitive that the
> superproject knows about some commits in its submodule.  "X, though
> Y" however makes it sound as if Y is true "despite X".  I do not
> think there is any "despite" here.

Re: [PATCH] glossary: add "remote" and "submodule"

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>>> +[[def_submodule]]submodule::
>>> +     A <<def_repository,repository>> inside another repository. The two
>>> +     repositories have different history, though the outer repository
>>> +     knows the commit of the inner repository.
>>
> ... But correctness trumps brevity indeed.

I do not think the correct way is that much longer, though.

A repository inside another repository. The two repositories have different history
A repository that holds the history of a separate project inside another repository

Heh, they are the same length, no?

>
>>
>>        A repository that holds the history of a separate project
>>        inside another repository (the latter of which is called
>>        superproject).
>
> This is better than what I proposed, but confusing. When naming
> a project a submodule, my mental standpoint is the superproject.
> ("This project has the submodule foo and bar"). But In your description
> the superproject is called "another repository".

That is because you are adding an entry for "submodule" to the
glossary, no?  I was writing from submodule's point of view, i.e. "I
(submodule) is inside another repository, and my project is separate
from that other repository's".

>>        The containing superproject knows about the
>>        names of (but does not hold copies of) commit objects of the
>>        contained submodules.
>
> That makes sense to point out here. Though should we also introduce
> "superproject" now?

Yes, that is what I was hinting at.

Re: [PATCH] glossary: add "remote" and "submodule"

[Stefan Beller]

On Wed, May 27, 2015 at 4:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>>>> +[[def_submodule]]submodule::
>>>> +     A <<def_repository,repository>> inside another repository. The two
>>>> +     repositories have different history, though the outer repository
>>>> +     knows the commit of the inner repository.
>>>
>> ... But correctness trumps brevity indeed.
>
> I do not think the correct way is that much longer, though.
>
> A repository inside another repository. The two repositories have different history
> A repository that holds the history of a separate project inside another repository
>
> Heh, they are the same length, no?
>
>>
>>>
>>>        A repository that holds the history of a separate project
>>>        inside another repository (the latter of which is called
>>>        superproject).
>>
>> This is better than what I proposed, but confusing. When naming
>> a project a submodule, my mental standpoint is the superproject.
>> ("This project has the submodule foo and bar"). But In your description
>> the superproject is called "another repository".
>
> That is because you are adding an entry for "submodule" to the
> glossary, no?  I was writing from submodule's point of view, i.e. "I
> (submodule) is inside another repository, and my project is separate
> from that other repository's".

The submodule doesn't know it's a submodule though, so the point of view
"I (as a submodule)" only happens rarely in the real world?
I have a library in mind when talking about submodules. And the libraries
maintainer may not care if their library is used as a submodule or just
"make install"ed or just put somewhere in the filesystem

Usually submodules are only interesting from the superprojects point of view,
like "I want to upgrade libfoo now, so I make a commit changing the gitlink
of the submodule to point at that tag/commit"
That's why I found the presented perspective a bit strange.

>
>>>        The containing superproject knows about the
>>>        names of (but does not hold copies of) commit objects of the
>>>        contained submodules.
>>
>> That makes sense to point out here. Though should we also introduce
>> "superproject" now?
>
> Yes, that is what I was hinting at.

ok

[PATCH] glossary: add "remote", "submodule", "superproject"

[Stefan Beller]

Noticed-by: Philip Oakley <philipoakley@iee.org>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/glossary-content.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index bf383c2..23ab692 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -469,6 +469,11 @@ The most notable example is `HEAD`.
 	<<def_push,push>> to describe the mapping between remote
 	<<def_ref,ref>> and local ref.
 
+[[def_remote]]remote repository::
+	A <<def_repository,repository>> which is used to track the same
+	project but resides somewhere else. To communicate with remotes,
+	see <<def_fetch,fetch>> or <<def_push,push>>.
+
 [[def_remote_tracking_branch]]remote-tracking branch::
 	A <<def_ref,ref>> that is used to follow changes from another
 	<<def_repository,repository>>. It typically looks like
@@ -515,6 +520,18 @@ The most notable example is `HEAD`.
 	is created by giving the `--depth` option to linkgit:git-clone[1], and
 	its history can be later deepened with linkgit:git-fetch[1].
 
+[[def_submodule]]submodule::
+	A <<def_repository,repository>> that holds the history of a
+	separate project inside another repository (the latter of
+	which is called <<def_superproject, superproject>>). The
+	containing superproject knows about the names of (but does
+	not hold copies of) commit objects of the contained submodules.
+
+[[def_superproject]]superproject::
+	A <<def_repository,repository>> that references other repositories
+	inside itself as <<def_submodule,submodules>>. The superproject
+	tracks only the remote and the name of the submodule.
+
 [[def_symref]]symref::
 	Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
 	id itself, it is of the format 'ref: refs/some/thing' and when
-- 
2.4.1.345.gab207b6.dirty

Re: [PATCH] glossary: add "remote", "submodule", "superproject"

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Noticed-by: Philip Oakley <philipoakley@iee.org>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  Documentation/glossary-content.txt | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)

The updates in this version relative to the previous one looks very
good, at least to me.  A bit more comments.

> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index bf383c2..23ab692 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.
>  	<<def_push,push>> to describe the mapping between remote
>  	<<def_ref,ref>> and local ref.
>  
> +[[def_remote]]remote repository::
> +	A <<def_repository,repository>> which is used to track the same
> +	project but resides somewhere else. To communicate with remotes,
> +	see <<def_fetch,fetch>> or <<def_push,push>>.
> +

The last sentence sounds a tiny bit strange, in that I have to do a
bit more than just see the explanation of these commands in order to
communicate with remotes.

But it probably is just me.

> @@ -515,6 +520,18 @@ The most notable example is `HEAD`.
>  	is created by giving the `--depth` option to linkgit:git-clone[1], and
>  	its history can be later deepened with linkgit:git-fetch[1].
>  
> +[[def_submodule]]submodule::
> +	A <<def_repository,repository>> that holds the history of a
> +	separate project inside another repository (the latter of
> +	which is called <<def_superproject, superproject>>). The
> +	containing superproject knows about the names of (but does
> +	not hold copies of) commit objects of the contained submodules.

I agree with one point you mentioned in one of your messages, which
is that a submodule is not aware that it is used as part of a larger
project.  That makes me wonder if the last sentence sits better in
the description of the superproject, rather than the description of
the submodule.

> +[[def_superproject]]superproject::
> +	A <<def_repository,repository>> that references other repositories
> +	inside itself as <<def_submodule,submodules>>.

Perhaps "repositories of other projects"?  Does "inside" make it
clear enough that we are talking about the relationship between
working trees of the superproject and submodules?

> +	The superproject
> +	tracks only the remote and the name of the submodule.

I am not sure what this sentence means [*1*], and I do not know if
(a corrected version of) such a description is necessary here.

Thanks.

[Footnote]

*1* The superproject records a bit more than "remote and name" in
.gitmodules, and of course it records the history of the paths that
the submodule is bound to over time, with specific commits from the
submodule in its history.

Re: [PATCH] glossary: add "remote", "submodule", "superproject"

[Stefan Beller]

On Thu, May 28, 2015 at 9:45 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> Noticed-by: Philip Oakley <philipoakley@iee.org>
>> Helped-by: Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>  Documentation/glossary-content.txt | 17 +++++++++++++++++
>>  1 file changed, 17 insertions(+)
>
> The updates in this version relative to the previous one looks very
> good, at least to me.  A bit more comments.
>
>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
>> index bf383c2..23ab692 100644
>> --- a/Documentation/glossary-content.txt
>> +++ b/Documentation/glossary-content.txt
>> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.
>>       <<def_push,push>> to describe the mapping between remote
>>       <<def_ref,ref>> and local ref.
>>
>> +[[def_remote]]remote repository::
>> +     A <<def_repository,repository>> which is used to track the same
>> +     project but resides somewhere else. To communicate with remotes,
>> +     see <<def_fetch,fetch>> or <<def_push,push>>.
>> +
>
> The last sentence sounds a tiny bit strange, in that I have to do a
> bit more than just see the explanation of these commands in order to
> communicate with remotes.

Maybe s/see/use/ here?

>
> But it probably is just me.
>
>> @@ -515,6 +520,18 @@ The most notable example is `HEAD`.
>>       is created by giving the `--depth` option to linkgit:git-clone[1], and
>>       its history can be later deepened with linkgit:git-fetch[1].
>>
>> +[[def_submodule]]submodule::
>> +     A <<def_repository,repository>> that holds the history of a
>> +     separate project inside another repository (the latter of
>> +     which is called <<def_superproject, superproject>>). The
>> +     containing superproject knows about the names of (but does
>> +     not hold copies of) commit objects of the contained submodules.
>
> I agree with one point you mentioned in one of your messages, which
> is that a submodule is not aware that it is used as part of a larger
> project.  That makes me wonder if the last sentence sits better in
> the description of the superproject, rather than the description of
> the submodule.

Moved in the upcoming reroll.

>
>> +[[def_superproject]]superproject::
>> +     A <<def_repository,repository>> that references other repositories
>> +     inside itself as <<def_submodule,submodules>>.
>
> Perhaps "repositories of other projects"?  Does "inside" make it
> clear enough that we are talking about the relationship between
> working trees of the superproject and submodules?


    A <<def_repository,repository>> that references repositories
    of other projects in its working tree as <<def_submodule,submodules>>.

>
>> +     The superproject
>> +     tracks only the remote and the name of the submodule.
>
> I am not sure what this sentence means [*1*], and I do not know if
> (a corrected version of) such a description is necessary here.

When looking at submodules and subtrees I feel they behave similar
to symbolic and hard links. If you delete the remote of the submodule
you need to take care when dealing with the superproject, similar
to repairing a dangling symlink. ("Is it gone or just moved? Where
do I point it now?")

My intend here was to show that submodules are fragile like symlinks are.

Usually a repository (or a file in that analogy) is quite self contained,
if you have a copy of the repository, you can do lots of operation on it
like reading, changing(writing), moving. If there is a broken (git/sym-)link
reading in full becomes a hassle, as parts are missing.

I am not sure if the discussion belongs into the glossary though.
But where would you start looking for information if you want to decided
whether to use submodules or subtrees?

>
> Thanks.
>
> [Footnote]
>
> *1* The superproject records a bit more than "remote and name" in
> .gitmodules, and of course it records the history of the paths that
> the submodule is bound to over time, with specific commits from the
> submodule in its history.
>

Re: [PATCH] glossary: add "remote", "submodule", "superproject"

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> I am not sure if the discussion belongs into the glossary though.

Probably not.  Perhaps in tutorial.