On Thu, May 28, 2015 at 9:45 AM, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> Stefan Beller <sbeller@xxxxxxxxxx> writes:
>
>> Noticed-by: Philip Oakley <philipoakley@xxxxxxx>
>> Helped-by: Junio C Hamano <gitster@xxxxxxxxx>
>> Signed-off-by: Stefan Beller <sbeller@xxxxxxxxxx>
>> ---
>> 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.
>
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html