{"thread":{"id":"9558","subject":"[PATCH] clarify need for init in git-submodules documentation","startedAt":"2007-08-16T18:10:02Z","lastAt":"2007-08-22T13:48:25Z","messageCount":13,"participants":["martin f. krafft","Sven Verdoolaege","martin f krafft","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"50898","messageId":"11872878021267-git-send-email-madduck@madduck.net","threadId":"9558","inReplyTo":null,"subject":"[PATCH] clarify need for init in git-submodules documentation","fromName":"martin f. krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-16T18:10:02Z","receivedAt":"2007-08-16T18:10:02Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"As per the discussion in this thread:\n\n  http://marc.info/?t=118721709500008&r=1&w=2\n\nthis patch updates the git-submodules documentation to make the situation a bit clearer.\n\nSigned-off-by: martin f. krafft <madduck@madduck.net>\n---\n Documentation/git-submodule.txt |   23 +++++++++++++++--------\n 1 files changed, 15 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 2c48936..b1a4f95 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -32,15 +32,17 @@ status::\n \trepository. This command is the default command for git-submodule.\n \n init::\n-\tInitialize the submodules, i.e. register in .git/config each submodule\n-\tname and url found in .gitmodules. The key used in .git/config is\n-\t`submodule.$name.url`. This command does not alter existing information\n-\tin .git/config.\n+\tInitialize the submodules, i.e. register in $GIT_DIR/config each\n+\tsubmodule name and url found in .gitmodules. The key used in\n+\t$GIT_DIR/config is `submodule.$name.url`. This command does not alter\n+\texisting information in $GIT_DIR/config, it only serves to initialise\n+\tthe local configuration from the defaults in .gitmodules.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached.\n+\tUpdate the submodules registered in $GIT_DIR/config, i.e. clone\n+\tmissing submodules and checkout the commit specified in the index of\n+\tthe containing repository. This will make the submodules HEAD be\n+\tdetached.\n \n \n OPTIONS\n@@ -64,9 +66,14 @@ FILES\n -----\n When initializing submodules, a .gitmodules file in the top-level directory\n of the containing repository is used to find the url of each submodule.\n-This file should be formatted in the same way as $GIR_DIR/config. The key\n+This file should be formatted in the same way as $GIT_DIR/config. The key\n to each submodule url is \"submodule.$name.url\".\n \n+The file .gitmodules serves default configuration data to users who cloned the\n+repository. In order to work with submodules, these data need to be copied to\n+$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config\n+are used for `git-submodule update`.\n+\n \n AUTHOR\n ------\n-- \n1.5.3.rc5.1.g44065\n"},{"id":"50927","messageId":"20070817093116.GH1070MdfPADPa@greensroom.kotnet.org","threadId":"9558","inReplyTo":"11872878021267-git-send-email-madduck@madduck.net","subject":"Re: [PATCH] clarify need for init in git-submodules documentation","fromName":"Sven Verdoolaege","fromEmail":"skimo@kotnet.org","sentAt":"2007-08-17T09:31:16Z","receivedAt":"2007-08-17T09:31:16Z","isPatch":true,"sender":{"key":"skimo@kotnet.org","avatar":null},"body":"On Thu, Aug 16, 2007 at 08:10:02PM +0200, martin f. krafft wrote:\n> +The file .gitmodules serves default configuration data to users who cloned the\n> +repository. In order to work with submodules, these data need to be copied to\n> +$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config\n> +are used for `git-submodule update`.\n> +\n\nThis is not true.  The url (which is local information) is taken from .git/config,\nthe name/path relation (which is shared information) is taken from .gitmodules.\n\nskimo\n\nPS, please don't prune (me from) the CC list when replying.\n"},{"id":"50928","messageId":"20070817100815.GC28477@piper.oerlikon.madduck.net","threadId":"9558","inReplyTo":"20070817093116.GH1070MdfPADPa@greensroom.kotnet.org","subject":"Re: [PATCH] clarify need for init in git-submodules documentation","fromName":"martin f krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-17T10:08:15Z","receivedAt":"2007-08-17T10:08:15Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:\n> This is not true.  The url (which is local information) is taken from .git/config,\n> the name/path relation (which is shared information) is taken from .gitmodules.\n\nIf you approve of this change, I shall prepare a new patch:\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex b1a4f95..2f69047 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -71,8 +71,9 @@ to each submodule url is \"submodule.$name.url\".\n \n The file .gitmodules serves default configuration data to users who cloned the\n repository. In order to work with submodules, these data need to be copied to\n-$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config\n-are used for `git-submodule update`.\n+$GIT_DIR/config with `git-submodule init`. Only the URL in $GIT_DIR/config\n+is used for `git-submodule update`, as it is local information. The name/path\n+relation is taken from the .gitmodules file, as it is shared data.\n \n \n AUTHOR\n\n-- \nmartin;              (greetings from the heart of the sun.)\n  \\____ echo mailto: !#^.\"<*>\"|tr \"<*> mailto:\" net@madduck\n \nin africa some of the native tribes have a custom of beating the\nground with clubs and uttering spine chilling cries. anthropologists\ncall this a form of primitive self-expression. in america they call\nit golf.\n \nspamtraps: madduck.bogus@madduck.net\n"},{"id":"50930","messageId":"20070817103652.GK1070MdfPADPa@greensroom.kotnet.org","threadId":"9558","inReplyTo":"20070817100815.GC28477@piper.oerlikon.madduck.net","subject":"Re: [PATCH] clarify need for init in git-submodules documentation","fromName":"Sven Verdoolaege","fromEmail":"skimo@kotnet.org","sentAt":"2007-08-17T10:36:52Z","receivedAt":"2007-08-17T10:36:52Z","isPatch":true,"sender":{"key":"skimo@kotnet.org","avatar":null},"body":"On Fri, Aug 17, 2007 at 12:08:15PM +0200, martin f krafft wrote:\n> also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:\n> > This is not true.  The url (which is local information) is taken from .git/config,\n> > the name/path relation (which is shared information) is taken from .gitmodules.\n> \n> If you approve of this change, I shall prepare a new patch:\n> \n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index b1a4f95..2f69047 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -71,8 +71,9 @@ to each submodule url is \"submodule.$name.url\".\n>  \n>  The file .gitmodules serves default configuration data to users who cloned the\n\nThis still seems to suggest that the only purpose of .gitmodules is to\ncontain default configuration data.  I think you should restrict the\nwhole paragraph to talking about URLs.  Btw, please be consistent about\nthe spelling of URL.  Either use \"url\" or change the \"url\"s in the remainder\nof the text to \"URL\".\nOh, and CC Lars on your patch.\n\n>  repository. In order to work with submodules, these data need to be copied to\n> -$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config\n> -are used for `git-submodule update`.\n> +$GIT_DIR/config with `git-submodule init`. Only the URL in $GIT_DIR/config\n> +is used for `git-submodule update`, as it is local information. The name/path\n> +relation is taken from the .gitmodules file, as it is shared data.\n\nThere is no mention in this man page of this relationship, so I think\nyou should either add a description or drop the last sentence.\nI'm also not sure if local/shared are the best way to describe the\ndistinction in a manual page.  I was only trying to make it clear to you.\n\nskimo\n"},{"id":"51052","messageId":"11875937841178-git-send-email-madduck@madduck.net","threadId":"9558","inReplyTo":"20070817103652.GK1070MdfPADPa@greensroom.kotnet.org","subject":"[PATCH] Clarify role of init command in git-submodules documentation","fromName":"martin f. krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-20T07:09:44Z","receivedAt":"2007-08-20T07:09:44Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"As per the discussion in this thread:\n\n  http://marc.info/?t=118721709500008&r=1&w=2\n\nthis patch updates the git-submodules documentation to make the situation\na bit clearer and documents the intended workflow.\n\nSigned-off-by: martin f. krafft <madduck@madduck.net>\n---\n Documentation/git-submodule.txt |   30 +++++++++++++++++++-----------\n 1 files changed, 19 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 2c48936..8bc818a 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -32,15 +32,17 @@ status::\n \trepository. This command is the default command for git-submodule.\n \n init::\n-\tInitialize the submodules, i.e. register in .git/config each submodule\n-\tname and url found in .gitmodules. The key used in .git/config is\n-\t`submodule.$name.url`. This command does not alter existing information\n-\tin .git/config.\n+\tInitialize the submodules, i.e. register in $GIT_DIR/config each\n+\tsubmodule name and url found in .gitmodules. The key used in\n+\t$GIT_DIR/config is `submodule.$name.url`. This command does not alter\n+\texisting information in $GIT_DIR/config, it only serves to initialise\n+\tthe local configuration from the defaults in .gitmodules.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached.\n+\tUpdate the submodules registered in $GIT_DIR/config, i.e. clone\n+\tmissing submodules and checkout the commit specified in the index of\n+\tthe containing repository. This will make the submodules HEAD be\n+\tdetached.\n \n \n OPTIONS\n@@ -62,10 +64,16 @@ OPTIONS\n \n FILES\n -----\n-When initializing submodules, a .gitmodules file in the top-level directory\n-of the containing repository is used to find the url of each submodule.\n-This file should be formatted in the same way as $GIR_DIR/config. The key\n-to each submodule url is \"submodule.$name.url\".\n+To work with submodules, a user has to prepare a repository clone with the\n+command `git-submodule init`. This command copies the url of each submodule\n+listed in the .gitmodules file in the top-level directory of the containing\n+repository to $GIT_DIR/config. The key to each submodule url is\n+\"submodule.$name.url\".\n+\n+The .gitmodules file then specifies the location of each submodule with\n+respect to the repository (and is shared among all contributors), while the\n+url of each submodule comes from the local configuration in $GIT_DIR/config\n+and can thus be modified independently of all other users.\n \n \n AUTHOR\n-- \n1.5.3.rc5.40.g2f82\n"},{"id":"51058","messageId":"20070820075459.GY1070MdfPADPa@greensroom.kotnet.org","threadId":"9558","inReplyTo":"11875937841178-git-send-email-madduck@madduck.net","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"Sven Verdoolaege","fromEmail":"skimo@kotnet.org","sentAt":"2007-08-20T07:54:59Z","receivedAt":"2007-08-20T07:54:59Z","isPatch":true,"sender":{"key":"skimo@kotnet.org","avatar":null},"body":"On Mon, Aug 20, 2007 at 09:09:44AM +0200, martin f. krafft wrote:\n>  FILES\n>  -----\n> -When initializing submodules, a .gitmodules file in the top-level directory\n> -of the containing repository is used to find the url of each submodule.\n> -This file should be formatted in the same way as $GIR_DIR/config. The key\n> -to each submodule url is \"submodule.$name.url\".\n> +To work with submodules, a user has to prepare a repository clone with the\n\nI think this is a bit ambiguous.\n\n> +command `git-submodule init`. This command copies the url of each submodule\n\nAs you can see in the \"init\" section of the man pages, the url is only\ncopied if it's not there already.\n\n> +listed in the .gitmodules file in the top-level directory of the containing\n> +repository to $GIT_DIR/config. The key to each submodule url is\n> +\"submodule.$name.url\".\n> +\n> +The .gitmodules file then specifies the location of each submodule with\n> +respect to the repository (and is shared among all contributors), while the\n> +url of each submodule comes from the local configuration in $GIT_DIR/config\n> +and can thus be modified independently of all other users.\n\nThis is better than the previous version, but in my mind still a bit confusing.\nLet me have a go:\n\n.gitmodules::\n\tThis file specifies the location of each submodule with respect\n\tto the top-level directory of the git working tree as well as\n\tthe default url of each submodule.  This default url is ignored\n\tby all git submodule subcommands, except init.  The latter can\n\tbe used to initialize the url in $GIR_DIR/config, which is the\n\turl used by the other subcommands.  This file is typically\n\ttracked as it contains information that is shared by all\n\tcontributors.  See also: gitlink:gitmodules[5].\n\n$GIT_DIR/config::\n\tThis files contains the url of each submodule in \"submodule.$name.url\".\n\tThese urls are required by git submodule subcommands such as update\n\tand can be initialized by calling \"git submodule init\".\n\tThe urls are specified in the local $GIT_DIR/config as the most\n\tappropriate url to get updates from may by different for different users\n\tand should not depend on the particular revision of the superproject\n\tthat is currently checked out.\n\nskimo\n"},{"id":"51072","messageId":"20070820092930.GA32563@piper.oerlikon.madduck.net","threadId":"9558","inReplyTo":"20070817093116.GH1070MdfPADPa@greensroom.kotnet.org","subject":"Not setting M-F-T, keeping people on Cc (was: [PATCH] clarify need for init in git-submodules documentation)","fromName":"martin f krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-20T09:29:30Z","receivedAt":"2007-08-20T09:29:30Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:\n> PS, please don't prune (me from) the CC list when replying.\n\nI am not used to lists where the policy is to CC posters, but seeing\nposts like http://marc.info/?l=git&m=113882569532399&w=2 and given\nmy newcomer/not-(yet-)important-contributor status, I am happy\nto comply (and apologise for not doing so earlier).\n\nTo help others in similar positions do the right thing I am sharing\nmy relevant mutt configuration:\n\n  # do not set M-F-T on mails to the git mailing list\n  send-hook . 'set followup_to'\n  send-hook '~C git@vger\\.kernel\\.org' 'unset followup_to'\n\nThis takes care of not sending M-F-T in outgoing mail. The remaining\nissue is how to ensure that those (and only those) people end up on\nCc who want to be there. I have come up with two ways: using mutt\nhooks and adding M-F-T to incoming mail:\n\n  # do a <group-reply> for L when sending to the git mailing list\n  # http://marc.info/?l=mutt-users&m=118734866910357&w=2\n  message-hook . 'bind pager L list-reply'\n  message-hook '~C git@vger\\.kernel\\.org' 'bind pager L group-reply'\n  macro index L '<display-message>L'\n\nThis is a bit ugly, but it works. However, since it interferes with\nsome other hooks and other parts of my configuration, I had to find\nanother way:\n\nthe theory is that my procmail *adds* the Mail-Followup-To header to\nincoming git list mails that don't have it yet, and puts all\nFrom/To/Cc addresses on there. This will cause my local mutt to\nbehave exactly like it should when I press L, but since the\nsend-hook has disabled followup_to, my reply will *not*\ncontain/propagate the Mail-Followup-To header.\n\n  :0\n  * ! ^Mail-Followup-To:\n  * ^TO_git@vger\\.kernel\\.org$\n  {\n    CORRESPONDENTS=`formail -cxTo: -xCc: -xFrom: | tr -s '\\n' ,`\n    :0 fw\n    |$FORMAIL -A \"Mail-Followup-To: $CORRESPONDENTS\"\n  }\n\nIn addition, I advice to unset metoo in mutt's configuration to\navoid CCing yourself on outgoing mail.\n\nNow all I need is to filter duplicate messages with procmail in such\na way that the list mail makes it through and the personal CC (which\nusually arrives first) is dropped:\n\n  :0\n  * ^X-Original-To: madduck@madduck\\.net$\n  * ^TO_git@vger\\.kernel\\.org$\n  /dev/null\n\nMake sure this happens *before* you weed out duplicate mail with\nformail.\n\nComments welcome, but off-list, please (Reply-To set). If important\nstuff turns up, I'll collect and append a summary to this thread in\na bit.\n\n-- \nmartin;              (greetings from the heart of the sun.)\n  \\____ echo mailto: !#^.\"<*>\"|tr \"<*> mailto:\" net@madduck\n \n\"for nasa, space is still a high priority.\" \n                                                      - george w. bush\n \nspamtraps: madduck.bogus@madduck.net\n"},{"id":"51134","messageId":"7vd4xhsybm.fsf@gitster.siamese.dyndns.org","threadId":"9558","inReplyTo":"11875937841178-git-send-email-madduck@madduck.net","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-20T21:14:37Z","receivedAt":"2007-08-20T21:14:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"martin f. krafft\" <madduck@madduck.net> writes:\n\n> As per the discussion in this thread:\n>\n>   http://marc.info/?t=118721709500008&r=1&w=2\n\nI'd rather see you summarize the conclusion of the thread here.\nHaving the URL as additional supporting reference is fine, but\nwhen one reviews the \"git log\" output, one is not necessarily\nonline.\n\n> this patch updates the git-submodules documentation to make the situation\n> a bit clearer and documents the intended workflow.\n>\n> Signed-off-by: martin f. krafft <madduck@madduck.net>\n\nThanks.  Some comments.\n\n> ---\n> ...\n>  init::\n> -\tInitialize the submodules, i.e. register in .git/config each submodule\n> -\tname and url found in .gitmodules. The key used in .git/config is\n> -\t`submodule.$name.url`. This command does not alter existing information\n> -\tin .git/config.\n> +\tInitialize the submodules, i.e. register in $GIT_DIR/config each\n> +\tsubmodule name and url found in .gitmodules. The key used in\n> +\t$GIT_DIR/config is `submodule.$name.url`. This command does not alter\n> +\texisting information in $GIT_DIR/config, it only serves to initialise\n> +\tthe local configuration from the defaults in .gitmodules.\n\n\ts/initialise/initialize/;\n\n>  FILES\n>  -----\n> -When initializing submodules, a .gitmodules file in the top-level directory\n> -of the containing repository is used to find the url of each submodule.\n> -This file should be formatted in the same way as $GIR_DIR/config. The key\n> -to each submodule url is \"submodule.$name.url\".\n> +To work with submodules, a user has to prepare a repository clone with the\n> +command `git-submodule init`.\n\nIs it \"a user _has_ to\"?  Or \"a user can use 'git submodule\ninit' to prepare?\"\n\nAnother thing that bothers me with this description is this.\nImagine you are a complete \"git submodule\" newbie (say, myself),\nand want to try applying this facility to your own project (say,\ngit.git).  So I first remove git-gui from git.git repository and\nthen try to add git-gui.git from Shawn as a submodule.  Surely,\nI am interested in the recipe \"To work with submodules\" at this\npoint, right?  Does that description apply to me?  Not really.\n\nSo this is not about \"_has_ to\" at all.  It is more like...\n\n    You may want to work on a project you cloned from somebody\n    else (we call that 'the superproject'), and find that the\n    superproject has .gitmodules file at the top.  This file\n    lists the subprojects that can be checked out in the\n    superproject.  To make a checkout of the subprojects of the\n    superproject you are interested in, you can use \"git\n    submodule init\" to help you prime data about submodules in\n    .git/config of the superproject.\n\n> .... This command copies the url of each submodule\n> +listed in the .gitmodules file in the top-level directory of the containing\n> +repository to $GIT_DIR/config. The key to each submodule url is\n> +\"submodule.$name.url\".\n\nI think we've seen most of that description in the above 'init::'.\n\nI've read Sven's description on two files.  My suspicion is that\ninstead of saying there are two files involved, it may be easier\nto understand if we tell the story like this:\n\n - \"git submodule\" subcommands typically use data from the git\n   configuration \"submodule.$name.$key\";\n\n - Definition of $name (e.g. it is just a logical token, not\n   necessarily the directory name, i.e. moving a subproject to\n   another directory does not have to change the $name).\n\n - Definition of possible $key (e.g. 'url'; others?)\n\n - After the initial clone of the superproject, you would not\n   have any of the necessary configuration variables in _your_\n   copy of the superproject.  There is a facility to help you\n   prime that information.  The project gives you .gitmodules,\n   and the tool gives you \"git submodule init\" to read from it.\n   Here is what the subcommand does...\n"},{"id":"51191","messageId":"20070821180218.GA14739@piper.oerlikon.madduck.net","threadId":"9558","inReplyTo":"7vd4xhsybm.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"martin f krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-21T18:02:18Z","receivedAt":"2007-08-21T18:02:18Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"also sprach Junio C Hamano <gitster@pobox.com> [2007.08.20.2314 +0200]:\n> > As per the discussion in this thread:\n> >\n> >   http://marc.info/?t=118721709500008&r=1&w=2\n> \n> I'd rather see you summarize the conclusion of the thread here.\n> Having the URL as additional supporting reference is fine, but\n> when one reviews the \"git log\" output, one is not necessarily\n> online.\n\nThis is a good point, and I completely agree with you. In this very\ncase, however, I *consciously* decided against a summary simply\nbecause I was hoping to capture the essence in the patch to the\ndocumentation itself. Anyway, I shall keep your suggestion in mind.\nThanks for being so patient with me.\n\nAnd while I still have your attention *grin*: I assume this is the\ncorrect way of going about this: keep sending updated patches to the\nsame thread until it's accepted?\n\nIn this case, I'll just send the text before preparing the next\npatch; once we agree on it, I'll send a patch. That should make it\neasier on everyone.\n\n> Is it \"a user _has_ to\"?  Or \"a user can use 'git submodule\n> init' to prepare?\"\n[...]\n> I've read Sven's description on two files.  My suspicion is that\n> instead of saying there are two files involved, it may be easier\n> to understand if we tell the story like this:\n\nBased your and Sven's suggestions, I sat down and thought for a bit,\nthen came up with this, which I like very much:\n\n  FILES\n\n  A repository with submodules is identified by a .gitmodules file\n  in the repository's top level (see gitlink:gitmodules[5]). This\n  file specifies for each submodule its name, the url of the\n  submodule's repository, as well as the location of the submodule\n  within the (super)project's repository. As the .gitmodules file\n  contains information shared by all users of the repository, it is\n  typically tracked.\n\n  Users who clone the project's repository need to initialize each\n  submodule before they can work with it. By initializing\n  a submodule, the submodule's url is copied from the .gitmodules\n  file to the (local) configuration in $GIT_DIR/config. The command\n  `git-submodule init` can be used for this, or the information\n  manually transferred. The key to each submodule's url in\n  $GIT_DIR/config is \"submodule.$name.url\".\n\n  Once a submodule's url is defined in $GIT_DIR/config, the\n  submodule can be cloned (from this url) into the local repository\n  with `git-submodule update` at the location specified in the\n  .gitmodules file.\n\n  By pulling the submodule urls out of $GIT_DIR/config,\n  git-submodule allows contributors to use different urls (e.g. via\n  ssh for those with an account) and also makes submodule urls\n  independent of the currently checked out revision of the\n  superproject.\n\nIn the process of writing this, I also added a bit to other parts of\nthe manpage:\n\n  - added reference to FILES section next to .gitmodules file\n    mention in description of add command, and a link to git-clone:\n\n      ... and registered in the .gitmodules file (see section\n      FILES). If no path is specified, the path is deduced from the\n      repository specification (just like gitlink:git-clone[1]).\n\n  - add to the update command description that modules can be\n    specificed on the command line:\n\n      Update all submodules registered in $GIT_DIR/config, or only\n      those specified as arguments on the command line.\n\n  - clarify what a detached HEAD is:\n\n      This will make the submodules HEAD be detached (it then\n      references a specific commit, not the tip of a branch anymore)\n\nI am looking forward to your comments!\n\nThanks again for your patience.\n\n-- \nmartin;              (greetings from the heart of the sun.)\n  \\____ echo mailto: !#^.\"<*>\"|tr \"<*> mailto:\" net@madduck\n \nif loving linux is wrong, i don't want to be right.\n \nspamtraps: madduck.bogus@madduck.net\n"},{"id":"51196","messageId":"20070821202516.GL1070MdfPADPa@greensroom.kotnet.org","threadId":"9558","inReplyTo":"20070821180218.GA14739@piper.oerlikon.madduck.net","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"Sven Verdoolaege","fromEmail":"skimo@kotnet.org","sentAt":"2007-08-21T20:25:16Z","receivedAt":"2007-08-21T20:25:16Z","isPatch":true,"sender":{"key":"skimo@kotnet.org","avatar":null},"body":"On Tue, Aug 21, 2007 at 08:02:18PM +0200, martin f krafft wrote:\n>   FILES\n\nI'm not sure this is the most appropriate name for this section.\n\n>   A repository with submodules is identified by a .gitmodules file\n>   in the repository's top level (see gitlink:gitmodules[5]). This\n>   file specifies for each submodule its name, the url of the\n>   submodule's repository, as well as the location of the submodule\n>   within the (super)project's repository. As the .gitmodules file\n>   contains information shared by all users of the repository, it is\n>   typically tracked.\n> \n>   Users who clone the project's repository need to initialize each\n>   submodule before they can work with it. By initializing\n\nI suppose this is implicit in the git submodule man page,\nbut this is only true if you actually want to use git submodule\nto work with the submodules.\n\n>   a submodule, the submodule's url is copied from the .gitmodules\n\nAs I mentioned before, this is not strictly true.\n(see init::)\n\n>   By pulling the submodule urls out of $GIT_DIR/config,\n>   git-submodule allows contributors to use different urls (e.g. via\n\nI'm not a native speaker, but to me that sounds like you are _not_\nusing the urls in $GIT_DIR/config.  That is, I read that as:\nthey are pulled out of $GIT_DIR/config (and then placed somewhere else).\n\nOther than that, it's definitely an improvement.\n\nskimo\n"},{"id":"51200","messageId":"20070821210349.GA16702@piper.oerlikon.madduck.net","threadId":"9558","inReplyTo":"20070821202516.GL1070MdfPADPa@greensroom.kotnet.org","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"martin f krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-21T21:03:49Z","receivedAt":"2007-08-21T21:03:49Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.21.2225 +0200]:\n> >   FILES\n> \n> I'm not sure this is the most appropriate name for this section.\n\nI was pondering this as well. BASIC CONCEPT might be better.\n\n> >   Users who clone the project's repository need to initialize each\n> >   submodule before they can work with it. By initializing\n> \n> I suppose this is implicit in the git submodule man page,\n\nIt wasn't to me; that's why I am doing all this.\n\nAnyway, when it comes to documentation, I don't think redundancy\nneeds to be avoided as much as otherwise, don't you agree?\n\n> but this is only true if you actually want to use git submodule to\n> work with the submodules.\n\nIs it? I tried this and after cloning a repo with submodules, it\ncreated the submodule directories alright, but it did not actually\ncheck them out/populate them, so they were empty.\n\n> >   a submodule, the submodule's url is copied from the\n> >   .gitmodules\n> \n> As I mentioned before, this is not strictly true. (see init::)\n\nYou're missing something like \"... unless the submodule is already\nregistered, in which case it won't be overwritten\", right?\n\n> >   By pulling the submodule urls out of $GIT_DIR/config,\n> >   git-submodule allows contributors to use different urls (e.g.\n> >   via\n> \n> I'm not a native speaker, but to me that sounds like you are _not_\n> using the urls in $GIT_DIR/config.  That is, I read that as: they\n> are pulled out of $GIT_DIR/config (and then placed somewhere\n> else).\n\nWell, the sentence says what I wanted to say, but you're absolutely\nright in that it could be improved. Something like\n\n  Since git-submodule uses the urls in $GIT_DIR/config, which is\n  a local configuration file, contributers are free to use urls\n  different from the default (e.g. via ssh for those with accounts).\n\n> Other than that, it's definitely an improvement.\n\nThanks,\n\n-- \nmartin;              (greetings from the heart of the sun.)\n  \\____ echo mailto: !#^.\"<*>\"|tr \"<*> mailto:\" net@madduck\n \n\"i like young girls. their stories are shorter.\"\n                                                        -- tom mcguane\n \nspamtraps: madduck.bogus@madduck.net\n"},{"id":"51228","messageId":"20070822083032.GN1070MdfPADPa@greensroom.kotnet.org","threadId":"9558","inReplyTo":"20070821210349.GA16702@piper.oerlikon.madduck.net","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"Sven Verdoolaege","fromEmail":"skimo@kotnet.org","sentAt":"2007-08-22T08:30:32Z","receivedAt":"2007-08-22T08:30:32Z","isPatch":true,"sender":{"key":"skimo@kotnet.org","avatar":null},"body":"On Tue, Aug 21, 2007 at 11:03:49PM +0200, martin f krafft wrote:\n> also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.21.2225 +0200]:\n> > >   Users who clone the project's repository need to initialize each\n> > >   submodule before they can work with it. By initializing\n> > \n> > I suppose this is implicit in the git submodule man page,\n> \n> It wasn't to me; that's why I am doing all this.\n\nI meant that the rest of my sentence could probably be\nimplicitly understood.\n\n> > but this is only true if you actually want to use git submodule to\n> > work with the submodules.\n> \n> Is it? I tried this and after cloning a repo with submodules, it\n> created the submodule directories alright, but it did not actually\n> check them out/populate them, so they were empty.\n\nSome people have been doing this manually or have homegrown scripts.\nNot that you should mention those options here.\n\n> \n> > >   a submodule, the submodule's url is copied from the\n> > >   .gitmodules\n> > \n> > As I mentioned before, this is not strictly true. (see init::)\n> \n> You're missing something like \"... unless the submodule is already\n> registered, in which case it won't be overwritten\", right?\n\nSomething like that, yes.\n\nskimo\n"},{"id":"51251","messageId":"20070822134825.GA14589@piper.oerlikon.madduck.net","threadId":"9558","inReplyTo":"20070822083032.GN1070MdfPADPa@greensroom.kotnet.org","subject":"Re: [PATCH] Clarify role of init command in git-submodules documentation","fromName":"martin f krafft","fromEmail":"madduck@madduck.net","sentAt":"2007-08-22T13:48:25Z","receivedAt":"2007-08-22T13:48:25Z","isPatch":true,"sender":{"key":"madduck@madduck.net","avatar":null},"body":"also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.22.1030 +0200]:\n> > > I suppose this is implicit in the git submodule man page,\n> > > but this is only true if you actually want to use git submodule to\n> > > work with the submodules.\n> >\n> I meant that the rest of my sentence could probably be\n> implicitly understood.\n\nAh. Okay, well, I'd say since this is the git-submodule manpage, we\ncan assume that they want to work with git-submodule.\n\n> > Is it? I tried this and after cloning a repo with submodules, it\n> > created the submodule directories alright, but it did not\n> > actually check them out/populate them, so they were empty.\n> \n> Some people have been doing this manually or have homegrown\n> scripts. Not that you should mention those options here.\n\nOk.\n\n> > You're missing something like \"... unless the submodule is already\n> > registered, in which case it won't be overwritten\", right?\n> \n> Something like that, yes.\n\nConsider it done. Patch forthcoming, though probably not tonight,\nI also want to give others more time to comment.\n\n-- \nmartin;              (greetings from the heart of the sun.)\n  \\____ echo mailto: !#^.\"<*>\"|tr \"<*> mailto:\" net@madduck\n \n\"of course the music is a great difficulty.\n you see, if one plays good music, people don't listen,\n and if one plays bad music people don't talk.\"\n                                                        -- oscar wilde\n \nspamtraps: madduck.bogus@madduck.net\n"}]}