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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2016, 18:09 UTC
Message-ID: <xmqqpon8f54i.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20161006235149.10232-1-sbeller@google.com>

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.

Show 12 quoted lines

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