Re: [PATCHv2] git-submodule.txt: Clarify 'init' and 'add' subcommands.

[Jens Lehmann <Jens.Lehmann@web.de>]

Am 16.05.2013 00:28, schrieb Dale R. Worley:
> Describe how 'add' sets the submodule's logical name, which is used in
> the configuration entry names.
> 
> Clarify that 'init' only sets up the configuration entries for
> submodules that have already been added elsewhere.  Describe that
> <path> arguments limit the submodules that are configured.
> 
> Signed-off-by: Dale Worley <worley@ariadne.com>

Thanks, this patch addresses all issues raised.

Acked-by: Jens Lehmann <Jens.Lehmann@web.de>

> ---
> This patch seems to have all the features that we have discussed:
> 
> - Describes how 'add' selects the submodule logical name, including
>   the effect of --name.  (My first patch was on a version of Git that
>   did not support --name, so I didn't know of it.)
> 
> - Corrects description of 'init' to clarify that its behavior is
>   driven by the gitlinks recorded in the index, rather than implying
>   it is driven by the contents of .gitmodules.
> 
> - Describes 'init' behavior to be driven by the index, rather than my
>   previous incorrect use of "file tree".  (Of course, gitlinks aren't
>   visible in the file tree.)
> 
> - Updated text for 'init' is shorter and less technical than my
>   previous patch.
> 
> - Since "(which were added and committed elsewhere)" is stated in the
>   first sentence, I've removed the later sentence explaining that
>   submodules must be added before they can be inited.
> 
> - Explains the effect of <path> arguments to 'init' subcommand.
> 
>  Documentation/git-submodule.txt |    8 ++++++--
>  1 files changed, 6 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index c99d795..83235c0 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -76,6 +76,8 @@ argument <path> is the relative location for the cloned submodule
>  to exist in the superproject. If <path> is not given, the
>  "humanish" part of the source repository is used ("repo" for
>  "/path/to/repo.git" and "foo" for "host.xz:foo/.git").
> +The <path> is also used as the submodule's logical name in its
> +configuration entries unless `--name` is used to specify a logical name.
>  +
>  <repository> is the URL of the new submodule's origin repository.
>  This may be either an absolute URL, or (if it begins with ./
> @@ -123,8 +125,10 @@ linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
>  too (and can also report changes to a submodule's work tree).
>  
>  init::
> -	Initialize the submodules, i.e. register each submodule name
> -	and url found in .gitmodules into .git/config.
> +	Initialize the submodules recorded in the index (which were
> +	added and committed elsewhere) by copying submodule
> +	names and urls from .gitmodules to .git/config.
> +	Optional <path> arguments limit which submodules will be initialized.
>  	It will also copy the value of `submodule.$name.update` into
>  	.git/config.
>  	The key used in .git/config is `submodule.$name.url`.
>