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".
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.)
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:
--- 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.
<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
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.)
+
update
Update the registered submodules, i.e. clone missing submodules and
checkout the commit specified in the index of the containing
Dale
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
