Re: [PATCH] documentation: clarify submodule.<name>.[url, path] variables

From: Junio C Hamano <gitster@pobox.com>
To: Stefan Beller <sbeller@google.com>
Cc: git@vger.kernel.org, Jens.Lehmann@web.de, hvoigt@hvoigt.net
Subject: Re: [PATCH] documentation: clarify submodule.<name>.[url, path] variables
Date: Mon, 10 Oct 2016 11:09:17 -0700	[thread overview]
Message-ID: <xmqqpon8f54i.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <20161006235149.10232-1-sbeller@google.com> (Stefan Beller's message of "Thu, 6 Oct 2016 16:51:49 -0700")

Stefan Beller <sbeller@google.com> writes:
>  submodule.<name>.path::
> +	The path within this project for a submodule. This variable is
> +	kept in the .gitmodules file. See linkgit:git-submodule[1] and
> +	linkgit:gitmodules[5] for details.

What does it exactly mean to be "kept"?

Does it mean "never appears in .git/config, and when it appears it
will not be used at all"?  If so we shouldn't even list it here.

I doubt there is any reason for .path to exist in .git/config; where
each submodule appears in the working tree is what is recorded in
the tree object, and the "identity" (i.e. that which links a
submodule in a tree to one of the repositories kept in
.git/modules/*) by reverse look-up of submodule.<name>.path from
in-tree .gitmodules, not from configuration, and it is not something
a per-repository configuration should be able to change at the
conceptual level.

>  submodule.<name>.url::
> -	The path within this project and URL for a submodule. These
> -	variables are initially populated by 'git submodule init'. See
> -	linkgit:git-submodule[1] and linkgit:gitmodules[5] for
> -	details.
> +	The URL for a submodule. This variable is copied from the .gitmodules
> +	file to the git config via 'git submodule init'. The user can change
> +	the configured URL before obtaining the submodule via 'git submodule
> +	update'. After obtaining the submodule, this variable is kept in the
> +	config as a boolean flag to indicate whether the submodule is of
> +	interest to git commands.  See linkgit:git-submodule[1] and
> +	linkgit:gitmodules[5] for details.

I think it is great that you are describing that this serves two
purposes, but "as a boolean flag" is very misleading.  It sounds as
if at some point "git submodule $something" command stores
true/false there.

 - It overrides the URL suggested by the project in .gitmodules and
   replace it with another URL viewed from the local environment
   (e.g. the project may suggest you to use http://github.com/ while
   you may have a local mirror elsewhere).

 - Its presence is also used as a sign that the user is interested in
   the submodule.