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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html