Re: Suggestion for improving the manual page for "git submodule"

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

Am 03.05.2013 03:23, schrieb Dale R. Worley:
> Several people have made similar mistakes in beliving that "git
> submodule init" can be used for adding submodules to a working
> directory, whereas "git submodule add" is the command that should be
> used.  That *is* documented at the top of the manual page for "git
> submodule", but my error was enhanced by a subtle error in the
> documentation of "init".

Thanks for bringing this up.

> The text as it is written suggests that init's behavior is driven by
> the contents of .submodules.  But in fact, its behavior is driven by
> the existing gitlinks in the file tree, possibly limited by the <path>
> arguments.  (Which is *why* "git submodule init" can't *add*
> submodules; it only processes *existing* submodules.)

That's correct (but I think "index" should be used here instead of
"file tree").

> I would like to suggest that the manual page be updated to remove the
> error in the description of the init subcommand, along with another
> addition to tell the submodule logical name that is used by the "add"
> subcommand:

Good idea, care to provide a patch? ;-)
(If so, please see Documentation/SubmittingPatches on how to do that)

> --- man1	2013-04-26 12:02:16.752702146 -0400
> +++ man3	2013-05-02 21:06:00.020353100 -0400
> @@ -61,6 +61,8 @@
>             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 used as the submodule's logical name in its
> +           configuration entries.

Nice, but I think you should append "unless the --name option is used
to provide a different name" or such to that sentence.

>             <repository> is the URL of the new submodule’s origin repository.
>             This may be either an absolute URL, or (if it begins with ./ or
> @@ -109,7 +111,9 @@
>             too (and can also report changes to a submodule’s work tree).
>  
>         init
> -           Initialize the submodules, i.e. register each submodule name and
> +           Initialize the submodules, i.e. register each submodule for which
> +           there is a gitlink recorded (or the specific gitlinks specified by
> +           <path> ...) by copying the name and

This sounds very technical ... maybe we should rephrase that like this?

-           Initialize the submodules, i.e. register each submodule name and
+           Initialize the submodules recorded in the index (by having been
+           added and committed somewhere else), i.e. register each submodule
+           name and

(Not being a native speaker I would appreciate if somebody else comes up
with a better wording. I think we should talk about the fact that somebody
else already "add"ed this submodule in his work tree; I'm not sure talking
about a gitlink here would help someone new to submodules that much, as this
topic seems to be about confusing "init" and "add".)

>             url found in .gitmodules into .git/config. The key used in
>             .git/config is submodule.$name.url. This command does not alter
>             existing information in .git/config. You can then customize the
> @@ -118,6 +122,10 @@
>             submodule update --init without the explicit init step if you do
>             not intend to customize any submodule locations.
>  
> +           (Because init only operates on existing gitlinks, it cannot
> +           be used to create submodules, regardless of the contents of
> +           .gitmodules.  Use the add subcommand to create submodules.)
> +

I'm not sure we need this anymore when we clarify the description above.

>         update
>             Update the registered submodules, i.e. clone missing submodules and
>             checkout the commit specified in the index of the containing