threads / discuss / 40505

Clarification on Submodule/Subproject naming

Subject: Clarification on Submodule/Subproject naming

## tl;dr

3 messages between Oct 6, 2015 and Oct 7, 2015.

replies: 2people: 3as markdown or json

Stefan Beller· Oct 6, 2015, 22:00 UTC · lore

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/

Jacob Keller· Oct 6, 2015, 22:05 UTC · re: Stefan Beller · lore

Re: Clarification on Submodule/Subproject naming

On Tue, Oct 6, 2015 at 3:00 PM, Stefan Beller <sbeller@google.com> wrote:

Show 15 quoted lines

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

Show 8 quoted lines

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

Jens Lehmann· Oct 7, 2015, 07:37 UTC · re: Stefan Beller · lore

Re: Clarification on Submodule/Subproject naming

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

Show 6 quoted lines

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

Show 5 quoted lines

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

Show 5 quoted lines

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