Clarification on Submodule/Subproject naming

Clarification on Submodule/Subproject naming

[Stefan Beller]

So a discussing started in a Gerrit change [1] if we want to name it
submodule or subproject.
We decided to stick with the git core convention of naming it
subproject for now.

But that lead me to the question: What is the difference of a
submodule and a subproject?

As far as I can tell they are synonyms (internally also called
GIT_LINK, but we never expose that to the users), where the term
submodule was coined later in the game, subproject being there as the
first term introduced in version 1.5.

So is it worth to unify that same concept hiding between two names?

Looking through the code we cannot switch to submodule as the literal
string "subproject"
is used for diffs in the plumbing layer.

But getting rid of submodule is also not easy, as there is
git-submodule.sh as a direct command.

So then there is also git subtree, which "allow subprojects to be
included within a subdirectory of the main project, optionally
including the subproject’s entire history." (the man page)

So can I understand a subproject as either a submodule or a subtree ?
If so would it make sense to add an entry to gitglossary to state that
subprojects are generic term for
having some kind of structure? (a subdirectory containing independent
stuff could be considered a
subproject. i.e. We could make contrib/examples the historic-git subproject ?)

Any advice welcome!
Stefan

[1] https://gerrit-review.googlesource.com/#/c/70948/

Re: Clarification on Submodule/Subproject naming

[Jacob Keller]

On Tue, Oct 6, 2015 at 3:00 PM, Stefan Beller <sbeller@google.com> wrote:
> So a discussing started in a Gerrit change [1] if we want to name it
> submodule or subproject.
> We decided to stick with the git core convention of naming it
> subproject for now.
>
> But that lead me to the question: What is the difference of a
> submodule and a subproject?
>
> As far as I can tell they are synonyms (internally also called
> GIT_LINK, but we never expose that to the users), where the term
> submodule was coined later in the game, subproject being there as the
> first term introduced in version 1.5.
>
> So is it worth to unify that same concept hiding between two names?
>

I think it would be worth trying to sync up at least documentation if
possible, and maybe even change the diff core output, but that depends
on whether we think changing that would break anyone? I'm not sure who
it would hurt to just start using "submodule" instead of "subproject"
there?

> Looking through the code we cannot switch to submodule as the literal
> string "subproject"
> is used for diffs in the plumbing layer.

Is there a strong reason we can't just change the diff layer to
"submodule" here? I'm not sure who or what that would hurt.

>
> But getting rid of submodule is also not easy, as there is
> git-submodule.sh as a direct command.
>

I think we should stick to submodule as that is the name of the
command as well as the general term understood by most users.
Subproject is the older name that was used before submodule.

> So then there is also git subtree, which "allow subprojects to be
> included within a subdirectory of the main project, optionally
> including the subproject’s entire history." (the man page)

I think the term subproject used here is used in a general sense, and
not in the specific sense used elsewhere.

>
> So can I understand a subproject as either a submodule or a subtree ?
> If so would it make sense to add an entry to gitglossary to state that
> subprojects are generic term for
> having some kind of structure? (a subdirectory containing independent
> stuff could be considered a
> subproject. i.e. We could make contrib/examples the historic-git subproject ?)
>

In terms of git diff core, subtrees are not shown as "subproject" in
the diffs at all, so I think in that sense subproject there is just an
artifact of what got used in the past.

> Any advice welcome!
> Stefan
>
> [1] https://gerrit-review.googlesource.com/#/c/70948/

Re: Clarification on Submodule/Subproject naming

[Jens Lehmann]

Am 07.10.2015 um 00:00 schrieb Stefan Beller:
> So a discussing started in a Gerrit change [1] if we want to name it
> submodule or subproject.
> We decided to stick with the git core convention of naming it
> subproject for now.

What convention? Isn't diff output the only place where we talk
about subprojects?

> But that lead me to the question: What is the difference of a
> submodule and a subproject?

A submodule is a certain kind subproject (using a GITLINK and a
.gitmodules entry), but e.g. a GITLINK could be used by other
tooling to represent subprojects without using a .gitmodules
file. So submodules are one in-core specialization of subprojects,
the other is git subtree (which doesn't even use GITLINKs).

> As far as I can tell they are synonyms (internally also called
> GIT_LINK, but we never expose that to the users), where the term
> submodule was coined later in the game, subproject being there as the
> first term introduced in version 1.5.
>
> So is it worth to unify that same concept hiding between two names?

I doubt that, as one is a subset of the other.

> Looking through the code we cannot switch to submodule as the literal
> string "subproject"
> is used for diffs in the plumbing layer.

Exactly, we cannot change that easily because of compatibility issues.

> But getting rid of submodule is also not easy, as there is
> git-submodule.sh as a direct command.

Yup, that would confuse lots of users and break tons of scripts.

> So then there is also git subtree, which "allow subprojects to be
> included within a subdirectory of the main project, optionally
> including the subproject’s entire history." (the man page)
>
> So can I understand a subproject as either a submodule or a subtree ?

Or even some other method of embedding another repo.

> If so would it make sense to add an entry to gitglossary to state that
> subprojects are generic term for
> having some kind of structure? (a subdirectory containing independent
> stuff could be considered a
> subproject. i.e. We could make contrib/examples the historic-git subproject ?)

Better documenting that is a good idea (though I'm not sure what you
mean by making "contrib/examples the historic-git subproject").