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

[Stefan Beller <sbeller@google.com>]

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.