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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html