Re: [PATCH] glossary: add "remote" and "submodule"
- From
Stefan Beller <sbeller@google.com>
- Date
- May 27, 2015, 22:59 UTC
- Message-ID
- <CAGZ79kbz6d8j1p5d-pO2cpou76ivhkCQPq4cpGxozc-9cnACPQ@mail.gmail.com>
- In-Reply-To
- <xmqq617dk621.fsf@gitster.dls.corp.google.com>
On Wed, May 27, 2015 at 3:29 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 36 quoted lines
> Stefan Beller <sbeller@google.com> writes: > >> Noticed-by: Philip Oakley <philipoakley@iee.org> >> Signed-off-by: Stefan Beller <sbeller@google.com> >> --- >> Documentation/glossary-content.txt | 10 ++++++++++ >> 1 file changed, 10 insertions(+) >> >> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt >> index bf383c2..e303135 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>>. >> + > > OK. > >> @@ -515,6 +520,11 @@ 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>> inside another repository. The two >> + repositories have different history, though the outer repository >> + knows the commit of the inner repository. > > I'd stress that they are not just different histories (as the > 'master' and the 'maint' branches of my project has different > histories) but they are separate projects. Perhaps like this?
This is a very subtle distinction IMHO, as both master and maint "are the same project". Looking from enough distance, it's just the git project without the fine detail of what makes these 2 histories different. I tried coming up with a short paragraph, which may explain my choice of words. But correctness trumps brevity indeed.
> > A repository that holds the history of a separate project > inside another repository (the latter of which is called > superproject).
This is better than what I proposed, but confusing. When naming a project a submodule, my mental standpoint is the superproject. ("This project has the submodule foo and bar"). But In your description the superproject is called "another repository".
> The containing superproject knows about the > names of (but does not hold copies of) commit objects of the > contained submodules.
That makes sense to point out here. Though should we also introduce "superproject" now?
Show 5 quoted lines
> > It is not like that it is strange or unintuitive that the > superproject knows about some commits in its submodule. "X, though > Y" however makes it sound as if Y is true "despite X". I do not > think there is any "despite" here.