Re: [PATCH] glossary: add "remote" and "submodule"

From: Junio C Hamano <gitster@pobox.com>
Date: May 27, 2015, 22:29 UTC
Message-ID: <xmqq617dk621.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1432761209-4120-1-git-send-email-sbeller@google.com>

Stefan Beller <sbeller@google.com> writes:

Show 19 quoted lines

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

Show 8 quoted lines

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

       A repository that holds the history of a separate project
       inside another repository (the latter of which is called
       superproject).  The containing superproject knows about the
       names of (but does not hold copies of) commit objects of the
       contained submodules.

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.