{"thread":{"id":"33709","subject":"Suggestion for improving the manual page for \"git submodule\"","startedAt":"2013-05-03T01:23:55Z","lastAt":"2013-05-03T20:48:18Z","messageCount":2,"participants":["Dale R. Worley","Jens Lehmann"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"216319","messageId":"201305030123.r431Nt6w015228@freeze.ariadne.com","threadId":"33709","inReplyTo":null,"subject":"Suggestion for improving the manual page for \"git submodule\"","fromName":"Dale R. Worley","fromEmail":"worley@alum.mit.edu","sentAt":"2013-05-03T01:23:55Z","receivedAt":"2013-05-03T01:23:55Z","isPatch":false,"sender":{"key":"worley@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/19911107?v=4"},"body":"Several people have made similar mistakes in beliving that \"git\nsubmodule init\" can be used for adding submodules to a working\ndirectory, whereas \"git submodule add\" is the command that should be\nused.  That *is* documented at the top of the manual page for \"git\nsubmodule\", but my error was enhanced by a subtle error in the\ndocumentation of \"init\".\n\nThe text as it is written suggests that init's behavior is driven by\nthe contents of .submodules.  But in fact, its behavior is driven by\nthe existing gitlinks in the file tree, possibly limited by the <path>\narguments.  (Which is *why* \"git submodule init\" can't *add*\nsubmodules; it only processes *existing* submodules.)\n\nI would like to suggest that the manual page be updated to remove the\nerror in the description of the init subcommand, along with another\naddition to tell the submodule logical name that is used by the \"add\"\nsubcommand:\n\n--- man1\t2013-04-26 12:02:16.752702146 -0400\n+++ man3\t2013-05-02 21:06:00.020353100 -0400\n@@ -61,6 +61,8 @@\n            to exist in the superproject. If <path> is not given, the\n            \"humanish\" part of the source repository is used (\"repo\" for\n            \"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\").\n+           The <path> is used as the submodule's logical name in its\n+           configuration entries.\n \n            <repository> is the URL of the new submodule’s origin repository.\n            This may be either an absolute URL, or (if it begins with ./ or\n@@ -109,7 +111,9 @@\n            too (and can also report changes to a submodule’s work tree).\n \n        init\n-           Initialize the submodules, i.e. register each submodule name and\n+           Initialize the submodules, i.e. register each submodule for which\n+           there is a gitlink recorded (or the specific gitlinks specified by\n+           <path> ...) by copying the name and\n            url found in .gitmodules into .git/config. The key used in\n            .git/config is submodule.$name.url. This command does not alter\n            existing information in .git/config. You can then customize the\n@@ -118,6 +122,10 @@\n            submodule update --init without the explicit init step if you do\n            not intend to customize any submodule locations.\n \n+           (Because init only operates on existing gitlinks, it cannot\n+           be used to create submodules, regardless of the contents of\n+           .gitmodules.  Use the add subcommand to create submodules.)\n+\n        update\n            Update the registered submodules, i.e. clone missing submodules and\n            checkout the commit specified in the index of the containing\n\nDale\n"},{"id":"216367","messageId":"51842292.9040400@web.de","threadId":"33709","inReplyTo":"201305030123.r431Nt6w015228@freeze.ariadne.com","subject":"Re: Suggestion for improving the manual page for \"git submodule\"","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2013-05-03T20:48:18Z","receivedAt":"2013-05-03T20:48:18Z","isPatch":false,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 03.05.2013 03:23, schrieb Dale R. Worley:\n> Several people have made similar mistakes in beliving that \"git\n> submodule init\" can be used for adding submodules to a working\n> directory, whereas \"git submodule add\" is the command that should be\n> used.  That *is* documented at the top of the manual page for \"git\n> submodule\", but my error was enhanced by a subtle error in the\n> documentation of \"init\".\n\nThanks for bringing this up.\n\n> The text as it is written suggests that init's behavior is driven by\n> the contents of .submodules.  But in fact, its behavior is driven by\n> the existing gitlinks in the file tree, possibly limited by the <path>\n> arguments.  (Which is *why* \"git submodule init\" can't *add*\n> submodules; it only processes *existing* submodules.)\n\nThat's correct (but I think \"index\" should be used here instead of\n\"file tree\").\n\n> I would like to suggest that the manual page be updated to remove the\n> error in the description of the init subcommand, along with another\n> addition to tell the submodule logical name that is used by the \"add\"\n> subcommand:\n\nGood idea, care to provide a patch? ;-)\n(If so, please see Documentation/SubmittingPatches on how to do that)\n\n> --- man1\t2013-04-26 12:02:16.752702146 -0400\n> +++ man3\t2013-05-02 21:06:00.020353100 -0400\n> @@ -61,6 +61,8 @@\n>             to exist in the superproject. If <path> is not given, the\n>             \"humanish\" part of the source repository is used (\"repo\" for\n>             \"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\").\n> +           The <path> is used as the submodule's logical name in its\n> +           configuration entries.\n\nNice, but I think you should append \"unless the --name option is used\nto provide a different name\" or such to that sentence.\n\n>             <repository> is the URL of the new submodule’s origin repository.\n>             This may be either an absolute URL, or (if it begins with ./ or\n> @@ -109,7 +111,9 @@\n>             too (and can also report changes to a submodule’s work tree).\n>  \n>         init\n> -           Initialize the submodules, i.e. register each submodule name and\n> +           Initialize the submodules, i.e. register each submodule for which\n> +           there is a gitlink recorded (or the specific gitlinks specified by\n> +           <path> ...) by copying the name and\n\nThis sounds very technical ... maybe we should rephrase that like this?\n\n-           Initialize the submodules, i.e. register each submodule name and\n+           Initialize the submodules recorded in the index (by having been\n+           added and committed somewhere else), i.e. register each submodule\n+           name and\n\n(Not being a native speaker I would appreciate if somebody else comes up\nwith a better wording. I think we should talk about the fact that somebody\nelse already \"add\"ed this submodule in his work tree; I'm not sure talking\nabout a gitlink here would help someone new to submodules that much, as this\ntopic seems to be about confusing \"init\" and \"add\".)\n\n>             url found in .gitmodules into .git/config. The key used in\n>             .git/config is submodule.$name.url. This command does not alter\n>             existing information in .git/config. You can then customize the\n> @@ -118,6 +122,10 @@\n>             submodule update --init without the explicit init step if you do\n>             not intend to customize any submodule locations.\n>  \n> +           (Because init only operates on existing gitlinks, it cannot\n> +           be used to create submodules, regardless of the contents of\n> +           .gitmodules.  Use the add subcommand to create submodules.)\n> +\n\nI'm not sure we need this anymore when we clarify the description above.\n\n>         update\n>             Update the registered submodules, i.e. clone missing submodules and\n>             checkout the commit specified in the index of the containing\n"}]}