Re: Suggestion for improving the manual page for "git submodule"
- From
Jens Lehmann <jens.lehmann@web.de>
- Date
- May 3, 2013, 20:48 UTC
- Message-ID
- <51842292.9040400@web.de>
- In-Reply-To
- <201305030123.r431Nt6w015228@freeze.ariadne.com>
Am 03.05.2013 03:23, schrieb Dale R. Worley:
Show 6 quoted lines
> 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.
Show 5 quoted lines
> 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)
Show 8 quoted lines
> --- 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.
Show 10 quoted lines
> <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".)
Show 11 quoted lines
> 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