From: Stefan Beller <sbeller@google.com>
Date: Thu, 28 May 2015 17:52:17 GMT
Subject: Re: [PATCH] glossary: add "remote", "submodule", "superproject"
Message-ID: <CAGZ79kb7M9L-xkMEG1GhAhYVWPR3env2fLiWt4fpbB=e6+jUhA@mail.gmail.com>
In-Reply-To: <xmqqk2vsirbe.fsf@gitster.dls.corp.google.com>

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