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

Stefan Beller [off-list ref] writes:

Noticed-by: Philip Oakley [off-list ref]
Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Stefan Beller <redacted>
---
 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.

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.

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.

On Thu, May 28, 2015 at 9:45 AM, Junio C Hamano [off-list ref] wrote:

Stefan Beller [off-list ref] writes:

quoted

Noticed-by: Philip Oakley [off-list ref]
Helped-by: Junio C Hamano [off-list ref]
Signed-off-by: Stefan Beller <redacted>
---
 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.

quoted

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.

quoted

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

quoted

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

quoted

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