{"thread":{"id":"46206","subject":"[PATCH/RFC] Cleanup Documentation","startedAt":"2017-06-19T03:05:47Z","lastAt":"2017-06-22T19:13:49Z","messageCount":15,"participants":["Kaartic Sivaraam","Junio C Hamano","Stefan Beller"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"322542","messageId":"20170619030518.6712-1-kaarticsivaraam91196@gmail.com","threadId":"46206","inReplyTo":null,"subject":"[PATCH/RFC] Cleanup Documentation","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-19T03:05:18Z","receivedAt":"2017-06-19T03:05:47Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"1. Remove redundancy from documentation\n2. Remove unclear reference to alternative\n\nSigned-off-by: Kaartic Sivaraam \n---\n\nThe following line seemes unclear and hence was removed for now. Suggest any\nchanges that could make it clear.\n\n\"This second form is provided to ease creating a new submodule from scratch, \nand presumes the user will later push the submodule to the given URL.\"\n\n\n Documentation/git-submodule.txt | 37 ++++++++++++++++---------------------\n 1 file changed, 16 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 74bc6200d..9812b0655 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -63,13 +63,7 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n \tto the changeset to be committed next to the current\n \tproject: the current project is termed the \"superproject\".\n +\n-This requires at least one argument: . The optional\n-argument is the relative location for the cloned submodule\n-to exist in the superproject. If 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 is also used as the submodule's logical name in its\n-configuration entries unless `--name` is used to specify a logical name.\n+This requires at least one argument: .\n +\n is the URL of the new submodule's origin repository.\n This may be either an absolute URL, or (if it begins with ./\n@@ -87,21 +81,22 @@ If the superproject doesn't have a default remote configured\n the superproject is its own authoritative upstream and the current\n working directory is used instead.\n +\n- is the relative location for the cloned submodule to\n-exist in the superproject. If does not exist, then the\n-submodule is created by cloning from the named URL. If does\n-exist and is already a valid Git repository, then this is added\n-to the changeset without cloning. This second form is provided\n-to ease creating a new submodule from scratch, and presumes\n-the user will later push the submodule to the given URL.\n+The optional argument is the relative location for the cloned\n+submodule to exist in the superproject. If 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\"). If \n+exists and is already a valid Git repository, then this is added\n+to the changeset without cloning. The is also used as the\n+submodule's logical name in its configuration entries unless `--name`\n+is used to specify a logical name.\n +\n-In either case, the given URL is recorded into .gitmodules for\n-use by subsequent users cloning the superproject. If the URL is\n-given relative to the superproject's repository, the presumption\n-is the superproject and submodule repositories will be kept\n-together in the same relative location, and only the\n-superproject's URL needs to be provided: git-submodule will correctly\n-locate the submodule using the relative URL in .gitmodules.\n+The given URL is recorded into .gitmodules for use by subsequent users\n+cloning the superproject. If the URL is given relative to the\n+superproject's repository, the presumption is the superproject and\n+submodule repositories will be kept together in the same relative\n+location, and only the superproject's URL needs to be provided.\n+git-submodule will correctly locate the submodule using the relative\n+URL in .gitmodules.\n \n status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n-- \n2.11.0\n\n"},{"id":"322548","messageId":"xmqq1sqgv9ax.fsf@gitster.mtv.corp.google.com","threadId":"46206","inReplyTo":"20170619030518.6712-1-kaarticsivaraam91196@gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-06-19T05:24:54Z","receivedAt":"2017-06-19T05:28:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan, this was sent in my way, but I know you are the primary\nperson who is looking into updating submodule documentation these\ndays, so I am forwarding it in your way to ask you to give the first\ncomment. \n\nThanks.\n\nKaartic Sivaraam writes:\n\n> 1. Remove redundancy from documentation\n> 2. Remove unclear reference to alternative\n>\n> Signed-off-by: Kaartic Sivaraam \n> ---\n>\n> The following line seemes unclear and hence was removed for now. Suggest any\n> changes that could make it clear.\n>\n> \"This second form is provided to ease creating a new submodule from scratch, \n> and presumes the user will later push the submodule to the given URL.\"\n>\n>\n> Documentation/git-submodule.txt | 37 ++++++++++++++++---------------------\n> 1 file changed, 16 insertions(+), 21 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 74bc6200d..9812b0655 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -63,13 +63,7 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n> \tto the changeset to be committed next to the current\n> \tproject: the current project is termed the \"superproject\".\n> +\n> -This requires at least one argument: . The optional\n> -argument is the relative location for the cloned submodule\n> -to exist in the superproject. If 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 is also used as the submodule's logical name in its\n> -configuration entries unless `--name` is used to specify a logical name.\n> +This requires at least one argument: .\n> +\n> is the URL of the new submodule's origin repository.\n> This may be either an absolute URL, or (if it begins with ./\n> @@ -87,21 +81,22 @@ If the superproject doesn't have a default remote configured\n> the superproject is its own authoritative upstream and the current\n> working directory is used instead.\n> +\n> - is the relative location for the cloned submodule to\n> -exist in the superproject. If does not exist, then the\n> -submodule is created by cloning from the named URL. If does\n> -exist and is already a valid Git repository, then this is added\n> -to the changeset without cloning. This second form is provided\n> -to ease creating a new submodule from scratch, and presumes\n> -the user will later push the submodule to the given URL.\n> +The optional argument is the relative location for the cloned\n> +submodule to exist in the superproject. If 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\"). If \n> +exists and is already a valid Git repository, then this is added\n> +to the changeset without cloning. The is also used as the\n> +submodule's logical name in its configuration entries unless `--name`\n> +is used to specify a logical name.\n> +\n> -In either case, the given URL is recorded into .gitmodules for\n> -use by subsequent users cloning the superproject. If the URL is\n> -given relative to the superproject's repository, the presumption\n> -is the superproject and submodule repositories will be kept\n> -together in the same relative location, and only the\n> -superproject's URL needs to be provided: git-submodule will correctly\n> -locate the submodule using the relative URL in .gitmodules.\n> +The given URL is recorded into .gitmodules for use by subsequent users\n> +cloning the superproject. If the URL is given relative to the\n> +superproject's repository, the presumption is the superproject and\n> +submodule repositories will be kept together in the same relative\n> +location, and only the superproject's URL needs to be provided.\n> +git-submodule will correctly locate the submodule using the relative\n> +URL in .gitmodules.\n> \n> status [--cached] [--recursive] [--] [...]::\n> \tShow the status of the submodules. This will print the SHA-1 of the\n"},{"id":"322549","messageId":"CAGZ79kbqBXZ5S2TBk6B5gRk+Y-ev2rdgkQZrF-MmHQc0Thj7EQ@mail.gmail.com","threadId":"46206","inReplyTo":"xmqq1sqgv9ax.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-06-19T05:50:54Z","receivedAt":"2017-06-19T05:51:00Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sun, Jun 18, 2017 at 10:24 PM, Junio C Hamano wrote:\n> Stefan, this was sent in my way, but I know you are the primary\n> person who is looking into updating submodule documentation these\n> days, so I am forwarding it in your way to ask you to give the first\n> comment.\n>\n> Thanks.\n\nAFAICT this is specific to the arguments of 'add', such that it would not\ncollide with sb/submodule-doc[1]. However my series was RFC, while this\nis on the order of \"documentation bug fix\", so this would be more important\nthan rewriting the documentation from scrach any way. :)\n\n\n\n[1] https://public-inbox.org/git/20170607185354.10050-1-sbeller@google.com/\n\n\n>\n> Kaartic Sivaraam writes:\n>\n>> 1. Remove redundancy from documentation\n>> 2. Remove unclear reference to alternative\n>>\n>> Signed-off-by: Kaartic Sivaraam \n>> ---\n>>\n>> The following line seemes unclear and hence was removed for now. Suggest any\n>> changes that could make it clear.\n>>\n>> \"This second form is provided to ease creating a new submodule from scratch,\n>> and presumes the user will later push the submodule to the given URL.\"\n\n+cc Marc who wrote this sentence originally.\n\n\n>>\n>>\n>> Documentation/git-submodule.txt | 37 ++++++++++++++++---------------------\n>> 1 file changed, 16 insertions(+), 21 deletions(-)\n>>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 74bc6200d..9812b0655 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -63,13 +63,7 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n>> to the changeset to be committed next to the current\n>> project: the current project is termed the \"superproject\".\n>> +\n>> -This requires at least one argument: . The optional\n>> -argument is the relative location for the cloned submodule\n>> -to exist in the superproject. If 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 is also used as the submodule's logical name in its\n>> -configuration entries unless `--name` is used to specify a logical name.\n>> +This requires at least one argument: .\n>> +\n\nSo we're losing the information how the submodule name is chosen.\nThis may be fine as I plan (long term) to make the name an arbitrary random\nstring (IMHO that reduces confusion as there will be less 'nearly the same'\nthings)\n\nOn the other hand the newly added line\n 'This requires at least one argument: > is the URL of the new submodule's origin repository.\n>> This may be either an absolute URL, or (if it begins with ./\n>> @@ -87,21 +81,22 @@ If the superproject doesn't have a default remote configured\n>> the superproject is its own authoritative upstream and the current\n>> working directory is used instead.\n>> +\n>> - is the relative location for the cloned submodule to\n>> -exist in the superproject. If does not exist, then the\n>> -submodule is created by cloning from the named URL. If does\n>> -exist and is already a valid Git repository, then this is added\n>> -to the changeset without cloning. This second form is provided\n>> -to ease creating a new submodule from scratch, and presumes\n>> -the user will later push the submodule to the given URL.\n>> +The optional argument is the relative location for the cloned\n>> +submodule to exist in the superproject. If 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\"). If \n>> +exists and is already a valid Git repository, then this is added\n>> +to the changeset without cloning. The is also used as the\n>> +submodule's logical name in its configuration entries unless `--name`\n>> +is used to specify a logical name.\n\nThis sounds good, it consolidates all information about []\nin one paragraph. While at it, maybe let's find another (better)\nsubstitute for \"humanish\" as that can be anything(?).\n\nMaybe \"the last part of the URL\" (without any .git)\n\n>> +\n>> -In either case, the given URL is recorded into .gitmodules for\n>> -use by subsequent users cloning the superproject. If the URL is\n>> -given relative to the superproject's repository, the presumption\n>> -is the superproject and submodule repositories will be kept\n>> -together in the same relative location, and only the\n>> -superproject's URL needs to be provided: git-submodule will correctly\n>> -locate the submodule using the relative URL in .gitmodules.\n>> +The given URL is recorded into .gitmodules for use by subsequent users\n>> +cloning the superproject. If the URL is given relative to the\n>> +superproject's repository, the presumption is the superproject and\n>> +submodule repositories will be kept together in the same relative\n>> +location, and only the superproject's URL needs to be provided.\n>> +git-submodule will correctly locate the submodule using the relative\n>> +URL in .gitmodules.\n>>\n\n(While at it:)\nPlease markup the '.gitmodules' either via single quotes or `.\n(or even link to 'gitmodules(5)' )\n\n>> status [--cached] [--recursive] [--] [...]::\n>> Show the status of the submodules. This will print the SHA-1 of the\n\nI am undecided if this is really removing (2) unclearness, but the\n(1) redundancy seems fine to me.\n\nThanks,\nStefan\n"},{"id":"322577","messageId":"1497893625.18850.2.camel@gmail.com","threadId":"46206","inReplyTo":"CAGZ79kbqBXZ5S2TBk6B5gRk+Y-ev2rdgkQZrF-MmHQc0Thj7EQ@mail.gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-19T17:33:45Z","receivedAt":"2017-06-19T17:34:05Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Sun, 2017-06-18 at 22:50 -0700, Stefan Beller wrote:\n> > > diff --git a/Documentation/git-submodule.txt b/Documentation/git-\n> > > submodule.txt\n> > > index 74bc6200d..9812b0655 100644\n> > > --- a/Documentation/git-submodule.txt\n> > > +++ b/Documentation/git-submodule.txt\n> > > @@ -63,13 +63,7 @@ add [-b ] [-f|--force] [--name ]\n> > > [--reference ] [--dep\n> > >       to the changeset to be committed next to the current\n> > >       project: the current project is termed the \"superproject\".\n> > >  +\n> > > -This requires at least one argument: . The optional\n> > > -argument is the relative location for the cloned\n> > > submodule\n> > > -to exist in the superproject. If 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 is also used as the submodule's logical name in its\n> > > -configuration entries unless `--name` is used to specify a\n> > > logical name.\n> > > +This requires at least one argument: .\n> > >  +\n> \n> So we're losing the information how the submodule name is chosen.\nI just moved it. I don't think we're losing anything related to how the\nname is chosen. Please let me know if I misinterpreted your statement.\n\n> This may be fine as I plan (long term) to make the name an arbitrary\n> random\n> string (IMHO that reduces confusion as there will be less 'nearly the\n> same'\n> things)\n> \n> On the other hand the newly added line\n>   'This requires at least one argument: (actually moved, but) is sort of redundant. The notation in the\n> argument line\n> should make that clear, already?\n> \nMakes clear sense. Removed it.\n\n> This sounds good, it consolidates all information about []\n> in one paragraph. While at it, maybe let's find another (better)\n> substitute for \"humanish\" as that can be anything(?).\n> \n> Maybe \"the last part of the URL\" (without any .git)\n> \nHow about \"meaningful\"? Put in place it reads like,\n\nIf is not given, the meaningful part of the source repository\n...\n\n> Please markup the '.gitmodules' either via single quotes or `.\n> (or even link to 'gitmodules(5)' )\n> \nMarked it up using `. Help needed to link to 'gitmodules(5)', as I'm\nnot sure how to provide alternative text to 'linkgit:'.\n\n> I am undecided if this is really removing (2) unclearness, but the\n> (1) redundancy seems fine to me.\n> \nSorry about that. The commit message should have been,\n\n...\n2. Removed unclear back reference\n...\n\nby which I intend to denote the following removal,\n> -In either case, the given URL is recorded into .gitmodules for\n> -use by subsequent users cloning the superproject.\n\nNote: Will follow up with a patch, soon.\n-- \nRegards,\nKaartic Sivaraam \n"},{"id":"322583","messageId":"CAGZ79kbMhQpxUa5TXK=WCzzKUCZ5vx3oC+fFTTozpgQihsUjTA@mail.gmail.com","threadId":"46206","inReplyTo":"1497893625.18850.2.camel@gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-06-19T17:54:21Z","receivedAt":"2017-06-19T17:54:27Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, Jun 19, 2017 at 10:33 AM, Kaartic Sivaraam\n wrote:\n\n>\n>> Please markup the '.gitmodules' either via single quotes or `.\n>> (or even link to 'gitmodules(5)' )\n>>\n> Marked it up using `. Help needed to link to 'gitmodules(5)', as I'm\n> not sure how to provide alternative text to 'linkgit:'.\n\nI did not mean 'gitmodules(5)' literally, I rather meant using linkgit:\nas you know it. :)\n\n>\n>> I am undecided if this is really removing (2) unclearness, but the\n>> (1) redundancy seems fine to me.\n>>\n> Sorry about that. The commit message should have been,\n>\n> ...\n> 2. Removed unclear back reference\n\nOh that clears some confusion here. :)\n\n> Note: Will follow up with a patch, soon.\n\nThanks.\nStefan\n"},{"id":"322674","messageId":"20170620031214.7616-1-kaarticsivaraam91196@gmail.com","threadId":"46206","inReplyTo":"CAGZ79kbMhQpxUa5TXK=WCzzKUCZ5vx3oC+fFTTozpgQihsUjTA@mail.gmail.com","subject":"[PATCH/RFC] Cleanup Documentation","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-20T03:12:14Z","receivedAt":"2017-06-20T03:12:49Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Make following changes to the git-submodule\ndocumentation:\n\n* Remove redundancy\n* Remove unclear back reference\n* Use more appropriate word\n* Quote important word\n\nSuggestions-by: Stefan Beller \nSigned-off-by: Kaartic Sivaraam \n---\n Currently used the word \"canonical\" instead of \"humanish\". If that word\n sounds more suitable then this is a [PATCH] and not a [PATCH/RFC].\n\n\n Documentation/git-submodule.txt | 37 +++++++++++++++----------------------\n 1 file changed, 15 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 74bc6200d..045fef417 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n \tto the changeset to be committed next to the current\n \tproject: the current project is termed the \"superproject\".\n +\n-This requires at least one argument: . The optional\n-argument is the relative location for the cloned submodule\n-to exist in the superproject. If 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 is also used as the submodule's logical name in its\n-configuration entries unless `--name` is used to specify a logical name.\n-+\n is the URL of the new submodule's origin repository.\n This may be either an absolute URL, or (if it begins with ./\n or ../), the location relative to the superproject's default remote\n@@ -87,21 +79,22 @@ If the superproject doesn't have a default remote configured\n the superproject is its own authoritative upstream and the current\n working directory is used instead.\n +\n- is the relative location for the cloned submodule to\n-exist in the superproject. If does not exist, then the\n-submodule is created by cloning from the named URL. If does\n-exist and is already a valid Git repository, then this is added\n-to the changeset without cloning. This second form is provided\n-to ease creating a new submodule from scratch, and presumes\n-the user will later push the submodule to the given URL.\n+The optional argument is the relative location for the cloned\n+submodule to exist in the superproject. If is not given, the\n+canonical part of the source repository is used (\"repo\" for\n+\"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\"). If \n+exists and is already a valid Git repository, then this is added\n+to the changeset without cloning. The is also used as the\n+submodule's logical name in its configuration entries unless `--name`\n+is used to specify a logical name.\n +\n-In either case, the given URL is recorded into .gitmodules for\n-use by subsequent users cloning the superproject. If the URL is\n-given relative to the superproject's repository, the presumption\n-is the superproject and submodule repositories will be kept\n-together in the same relative location, and only the\n-superproject's URL needs to be provided: git-submodule will correctly\n-locate the submodule using the relative URL in .gitmodules.\n+The given URL is recorded into `.gitmodules` for use by subsequent users\n+cloning the superproject. If the URL is given relative to the\n+superproject's repository, the presumption is the superproject and\n+submodule repositories will be kept together in the same relative\n+location, and only the superproject's URL needs to be provided.\n+git-submodule will correctly locate the submodule using the relative\n+URL in .gitmodules.\n \n status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n-- \n2.11.0\n\n"},{"id":"322742","messageId":"CAGZ79kbJx4p2y6Vjp3dVBP2pd=MYa_j3Mxfv=zUygHY-bHj0wQ@mail.gmail.com","threadId":"46206","inReplyTo":"20170620031214.7616-1-kaarticsivaraam91196@gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-06-20T16:57:59Z","receivedAt":"2017-06-20T16:58:06Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, Jun 19, 2017 at 8:12 PM, Kaartic Sivaraam\n wrote:\n> Make following changes to the git-submodule\n> documentation:\n>\n> * Remove redundancy\n> * Remove unclear back reference\n> * Use more appropriate word\n> * Quote important word\n>\n> Suggestions-by: Stefan Beller \n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Currently used the word \"canonical\" instead of \"humanish\". If that word\n> sounds more suitable then this is a [PATCH] and not a [PATCH/RFC].\n\ncanonical: \"according to recognized rules or scientific laws.\"\nsounds about right. :)\n\n>\n> Documentation/git-submodule.txt | 37 +++++++++++++++----------------------\n> 1 file changed, 15 insertions(+), 22 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 74bc6200d..045fef417 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n> to the changeset to be committed next to the current\n> project: the current project is termed the \"superproject\".\n> +\n> -This requires at least one argument: . The optional\n> -argument is the relative location for the cloned submodule\n> -to exist in the superproject. If 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 is also used as the submodule's logical name in its\n> -configuration entries unless `--name` is used to specify a logical name.\n> -+\n> is the URL of the new submodule's origin repository.\n> This may be either an absolute URL, or (if it begins with ./\n> or ../), the location relative to the superproject's default remote\n> @@ -87,21 +79,22 @@ If the superproject doesn't have a default remote configured\n> the superproject is its own authoritative upstream and the current\n> working directory is used instead.\n> +\n> - is the relative location for the cloned submodule to\n> -exist in the superproject. If does not exist, then the\n> -submodule is created by cloning from the named URL. If does\n> -exist and is already a valid Git repository, then this is added\n> -to the changeset without cloning. This second form is provided\n> -to ease creating a new submodule from scratch, and presumes\n> -the user will later push the submodule to the given URL.\n> +The optional argument is the relative location for the cloned\n> +submodule to exist in the superproject. If is not given, the\n> +canonical part of the source repository is used (\"repo\" for\n> +\"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\"). If \n> +exists and is already a valid Git repository, then this is added\n> +to the changeset without cloning.\n\nWhile this was just reflowed and not newly introduced, I am still left\nwondering what a changeset is in Git terms. Our Documentation/glossary\nsays:\n\n [[def_changeset]]changeset::\n BitKeeper/cvsps speak for \"<>\". Since Git does not\n store changes, but states, it really does not make sense to use the term\n \"changesets\" with Git.\n\nMaybe we should say instead:\n\n If exists and is already a valid Git repository,\n then this is staged for commit without cloning.\n\n\n\n\n> The is also used as the\n> +submodule's logical name in its configuration entries unless `--name`\n> +is used to specify a logical name.\n> +\n> -In either case, the given URL is recorded into .gitmodules for\n> -use by subsequent users cloning the superproject. If the URL is\n> -given relative to the superproject's repository, the presumption\n> -is the superproject and submodule repositories will be kept\n> -together in the same relative location, and only the\n> -superproject's URL needs to be provided: git-submodule will correctly\n> -locate the submodule using the relative URL in .gitmodules.\n> +The given URL is recorded into `.gitmodules` for use by subsequent users\n> +cloning the superproject. If the URL is given relative to the\n> +superproject's repository, the presumption is the superproject and\n> +submodule repositories will be kept together in the same relative\n> +location, and only the superproject's URL needs to be provided.\n> +git-submodule will correctly locate the submodule using the relative\n> +URL in .gitmodules.\n>\n\nWith or without this nit addressed, this patch looks good to me,\n\nThanks,\nStefan\n"},{"id":"322743","messageId":"CAGZ79kbJB8dFUYu_70TAYbFWxLQiACEWMrE8M71GSEpnXqqzQQ@mail.gmail.com","threadId":"46206","inReplyTo":"CAGZ79kbJx4p2y6Vjp3dVBP2pd=MYa_j3Mxfv=zUygHY-bHj0wQ@mail.gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-06-20T17:05:45Z","receivedAt":"2017-06-20T17:05:52Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jun 20, 2017 at 9:57 AM, Stefan Beller wrote:\n>\n> With or without this nit addressed, this patch looks good to me,\n>\n\nWell actually not quite. The subject (and commit message) is very vague,\nmaybe:\n\n Documentation/git-submodule: cleanup \"add\" section\n\n The \"add\" section for 'git-submodule' is redundant in its description and\n the short synopsis line. Remove the redundant mentioning of the\n 'repository' argument being mandatory.\n\n The text is hard to read because of back-references, so remove those.\n\n Replace the word \"humanish\" by \"canonical\" as that conveys better what\n we do to guess the path.\n\n While at it, quote all occurrences of '.gitmodules' as that is an important\n file in the submodule context, also link to it on its first mention.\n (This paragraph is not exactly what happens in the commit, but I wrote it\n as a way how I would write commit messages. It shows the reader how\n you addressed the given problem, with the quantifiers \"all\" \"the\nfirst\" showing\n what you think is important, and that you deliberately omitted others)\n"},{"id":"322750","messageId":"1497983273.28187.9.camel@gmail.com","threadId":"46206","inReplyTo":"CAGZ79kbJx4p2y6Vjp3dVBP2pd=MYa_j3Mxfv=zUygHY-bHj0wQ@mail.gmail.com","subject":"Re: [PATCH/RFC] Cleanup Documentation","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-20T18:27:53Z","receivedAt":"2017-06-20T18:28:34Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Tue, 2017-06-20 at 09:57 -0700, Stefan Beller wrote:\n> canonical: \"according to recognized rules or scientific laws.\"\n> sounds about right. :)\n> \nI actually used as I found it to have the meaning of \"conforming to\northodox or recognized rules\" :)\n\n\n> While this was just reflowed and not newly introduced, I am still\n> left wondering what a changeset is in Git terms. Our\n> Documentation/glossary says:\n> \n>   [[def_changeset]]changeset::\n>   BitKeeper/cvsps speak for \"<>\". Since Git does\n> not store changes, but states, it really does not make sense to use\n> the term \"changesets\" with Git.\n> \n> Maybe we should say instead:\n> \n>     If exists and is already a valid Git repository,\n>     then this is staged for commit without cloning.\n> \nDoes seem to be a good change to make. Done.\n\nOn Tue, 2017-06-20 at 10:05 -0700, Stefan Beller wrote:\n> > On Tue, Jun 20, 2017 at 9:57 AM, Stefan Beller \n> > wrote:\n> > > \n> > > With or without this nit addressed, this patch looks good to me,\n> > > \n> > \n> > Well actually not quite. The subject (and commit message) is very\n> > vague,\n> > maybe:\n> \n> >     Documentation/git-submodule: cleanup \"add\" section\n> > \n> >     The \"add\" section for 'git-submodule' is redundant in its\n> > description and\n> >     the short synopsis line. Remove the redundant mentioning of the\n> >     'repository' argument being mandatory.\n> > \n> >     The text is hard to read because of back-references, so remove\n> > those.\n> > \n> >     Replace the word \"humanish\" by \"canonical\" as that conveys\n> better\n> > what\n> >     we do to guess the path.\n> > \n> >     While at it, quote all occurrences of '.gitmodules' as that is\n> an\n> > important\n> >     file in the submodule context, also link to it on its first\n> > mention.\n> >     (This paragraph is not exactly what happens in the commit, but\n> I\n> > wrote it\n> >     as a way how I would write commit messages. It shows the reader\n> > how\n> >     you addressed the given problem, with the quantifiers \"all\"\n> \"the\n> > first\" showing\n> >     what you think is important, and that you deliberately omitted\n> > others)\n> \nMade this change too.\n\n\n-- \nRegards,\nKaartic Sivaraam \n"},{"id":"322799","messageId":"1498014140.5419.3.camel@gmail.com","threadId":"46206","inReplyTo":"CAGZ79kbJB8dFUYu_70TAYbFWxLQiACEWMrE8M71GSEpnXqqzQQ@mail.gmail.com","subject":"[PATCH/FINALRFC] Documentation/git-submodule: cleanup","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-21T03:02:20Z","receivedAt":"2017-06-21T03:02:38Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"The \"add\" section for 'git-submodule' is redundant in\nits description and the short synopsis line. Fix it.\n\nRemove the redundant mentioning of the 'repository' argument\nbeing mandatory.\n\nThe text is hard to read because of back-references, so remove\nthose.\n\nReplace the word \"humanish\" by \"canonical\" as that conveys better\nwhat we do to guess the path.\n\nWhile at it, quote all occurrences of '.gitmodules' as that is an\nimportant file in the submodule context, also link to it on its\nfirst mention.\n\nHelped-by: Stefan Beller \nSigned-off-by: Kaartic Sivaraam \n---\n In case no other changes are required then this is the final version\n of the patch.\n\n\n Documentation/git-submodule.txt | 49 ++++++++++++++++++---------------\n--------\n 1 file changed, 21 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-\nsubmodule.txt\nindex 74bc6200d..6e07bade3 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [\n--reference ] [--dep\n \tto the changeset to be committed next to the current\n \tproject: the current project is termed the \"superproject\".\n +\n-This requires at least one argument: . The optional\n-argument is the relative location for the cloned submodule\n-to exist in the superproject. If 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 is also used as the submodule's logical name in its\n-configuration entries unless `--name` is used to specify a logical\nname.\n-+\n  is the URL of the new submodule's origin repository.\n This may be either an absolute URL, or (if it begins with ./\n or ../), the location relative to the superproject's default remote\n@@ -87,21 +79,22 @@ If the superproject doesn't have a default remote\nconfigured\n the superproject is its own authoritative upstream and the current\n working directory is used instead.\n +\n- is the relative location for the cloned submodule to\n-exist in the superproject. If does not exist, then the\n-submodule is created by cloning from the named URL. If does\n-exist and is already a valid Git repository, then this is added\n-to the changeset without cloning. This second form is provided\n-to ease creating a new submodule from scratch, and presumes\n-the user will later push the submodule to the given URL.\n+The optional argument is the relative location for the cloned\n+submodule to exist in the superproject. If is not given, the\n+canonical part of the source repository is used (\"repo\" for\n+\"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\"). If \n+exists and is already a valid Git repository, then it is staged\n+for commit without cloning. The is also used as the submodule's\n+logical name in its configuration entries unless `--name` is used\n+to specify a logical name.\n +\n-In either case, the given URL is recorded into .gitmodules for\n-use by subsequent users cloning the superproject. If the URL is\n-given relative to the superproject's repository, the presumption\n-is the superproject and submodule repositories will be kept\n-together in the same relative location, and only the\n-superproject's URL needs to be provided: git-submodule will correctly\n-locate the submodule using the relative URL in .gitmodules.\n+The given URL is recorded into `.gitmodules` for use by subsequent\nusers\n+cloning the superproject. If the URL is given relative to the\n+superproject's repository, the presumption is the superproject and\n+submodule repositories will be kept together in the same relative\n+location, and only the superproject's URL needs to be provided.\n+git-submodule will correctly locate the submodule using the relative\n+URL in `.gitmodules`.\n \n status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1\nof the\n@@ -123,7 +116,7 @@ too (and can also report changes to a submodule's\nwork tree).\n init [--] [...]::\n \tInitialize the submodules recorded in the index (which were\n \tadded and committed elsewhere) by setting\n`submodule.$name.url`\n-\tin .git/config. It uses the same setting from .gitmodules as\n+\tin .git/config. It uses the same setting from `.gitmodules` as\n \ta template. If the URL is relative, it will be resolved using\n \tthe default remote. If there is no default remote, the current\n \trepository will be assumed to be upstream.\n@@ -197,7 +190,7 @@ configuration variable:\n \tnone;; the submodule is not updated.\n \n If the submodule is not yet initialized, and you just want to use the\n-setting as stored in .gitmodules, you can automatically initialize the\n+setting as stored in `.gitmodules`, you can automatically initialize\nthe\n submodule with the `--init` option.\n \n If `--recursive` is specified, this command will recurse into the\n@@ -220,7 +213,7 @@ foreach [--recursive] ::\n \tEvaluates an arbitrary shell command in each checked out\nsubmodule.\n \tThe command has access to the variables $name, $path, $sha1\nand\n \t$toplevel:\n-\t$name is the name of the relevant submodule section in\n.gitmodules,\n+\t$name is the name of the relevant submodule section in\n`.gitmodules`,\n \t$path is the name of the submodule directory relative to the\n \tsuperproject, $sha1 is the commit as recorded in the\nsuperproject,\n \tand $toplevel is the absolute path to the top-level of the\nsuperproject.\n@@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse\nHEAD`'\n \n sync [--recursive] [--] [...]::\n \tSynchronizes submodules' remote URL configuration setting\n-\tto the value specified in .gitmodules. It will only affect\nthose\n+\tto the value specified in `.gitmodules`. It will only affect\nthose\n \tsubmodules which already have a URL entry in .git/config (that\nis the\n \tcase when they are initialized or freshly added). This is\nuseful when\n \tsubmodule URLs change upstream and you need to update your\nlocal\n@@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `\n--shared` options carefully.\n --[no-]recommend-shallow::\n \tThis option is only valid for the update command.\n \tThe initial clone of a submodule will use the recommended\n-\t`submodule..shallow` as provided by the .gitmodules file\n+\t`submodule..shallow` as provided by the `.gitmodules`\nfile\n \tby default. To ignore the suggestions use `--no-recommend-\nshallow`.\n \n -j ::\n@@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `\n--shared` options carefully.\n \n FILES\n -----\n-When initializing submodules, a .gitmodules file in the top-level\ndirectory\n+When initializing submodules, a `.gitmodules` file in the top-level\ndirectory\n of the containing repository is used to find the url of each\nsubmodule.\n This file should be formatted in the same way as `$GIT_DIR/config`.\nThe key\n to each submodule url is \"submodule.$name.url\".  See\nlinkgit:gitmodules[5]\n-- \n2.11.0\n"},{"id":"322816","messageId":"xmqq4lv9s4lr.fsf@gitster.mtv.corp.google.com","threadId":"46206","inReplyTo":"1498014140.5419.3.camel@gmail.com","subject":"Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-06-21T16:11:28Z","receivedAt":"2017-06-21T16:33:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kaartic Sivaraam writes:\n\n> Helped-by: Stefan Beller \n> Signed-off-by: Kaartic Sivaraam \n> ---\n>  In case no other changes are required then this is the final version\n> of the patch.\n>\n>\n>  Documentation/git-submodule.txt | 49 ++++++++++++++++++---------------\n> --------\n>  1 file changed, 21 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-\n> submodule.txt\n> index 74bc6200d..6e07bade3 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [\n> --reference ] [--dep\n\nThe patch is heavily line-wrapped and whitespace broken, unlike\nprevious patch messages you sent to the list. \n\nDid you do something differently?\n"},{"id":"322825","messageId":"1498066891.32360.1.camel@gmail.com","threadId":"46206","inReplyTo":"xmqq4lv9s4lr.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-21T17:41:31Z","receivedAt":"2017-06-21T17:41:48Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Wed, 2017-06-21 at 09:11 -0700, Junio C Hamano wrote:\n> Kaartic Sivaraam writes:\n> \n> > Helped-by: Stefan Beller \n> > Signed-off-by: Kaartic Sivaraam \n> > ---\n> >  In case no other changes are required then this is the final\n> > version\n> >  of the patch.\n> > \n> > \n> >  Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------\n> > ----\n> > --------\n> >  1 file changed, 21 insertions(+), 28 deletions(-)\n> > \n> > diff --git a/Documentation/git-submodule.txt b/Documentation/git-\n> > submodule.txt\n> > index 74bc6200d..6e07bade3 100644\n> > --- a/Documentation/git-submodule.txt\n> > +++ b/Documentation/git-submodule.txt\n> > @@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [\n> > --reference ] [--dep\n> \n> The patch is heavily line-wrapped and whitespace broken, unlike\n> previous patch messages you sent to the list.  \n> \n> Did you do something differently?\nYes. Sorry about that. Due to some issue with the firewall in the\nnetwork I use, I couldn't send patches using 'send-email' so I used the\nemail-client (evolution) to send the patch believing it wouldn't damage\nit. It crapped with the formatting. Sorry again, will be careful in\nfuture (for which I have to find a work-around).\n\n-- \nRegards,\nKaartic Sivaraam \n"},{"id":"322910","messageId":"0102015ccdb6695c-7a8b1188-5bbe-43d1-8a8f-913c006c2474-000000@eu-west-1.amazonses.com","threadId":"46206","inReplyTo":"1498066891.32360.1.camel@gmail.com","subject":"[PATCH/FINAL] Documentation/git-submodule: cleanup","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-06-22T02:51:42Z","receivedAt":"2017-06-22T02:51:50Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"The \"add\" section for 'git-submodule' is redundant in\nits description and the short synopsis line. Fix it.\n\nRemove the redundant mentioning of the 'repository' argument\nbeing mandatory.\n\nThe text is hard to read because of back-references, so remove\nthose.\n\nReplace the word \"humanish\" by \"canonical\" as that conveys better\nwhat we do to guess the path.\n\nWhile at it, quote all occurrences of '.gitmodules' as that is an\nimportant file in the submodule context, also link to it on its\nfirst mention.\n\nHelped-by: Stefan Beller \nSigned-off-by: Kaartic Sivaraam \n---\n Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------------------\n 1 file changed, 21 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 74bc6200d564c..6e07bade39a7c 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n \tto the changeset to be committed next to the current\n \tproject: the current project is termed the \"superproject\".\n +\n-This requires at least one argument: . The optional\n-argument is the relative location for the cloned submodule\n-to exist in the superproject. If 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 is also used as the submodule's logical name in its\n-configuration entries unless `--name` is used to specify a logical name.\n-+\n is the URL of the new submodule's origin repository.\n This may be either an absolute URL, or (if it begins with ./\n or ../), the location relative to the superproject's default remote\n@@ -87,21 +79,22 @@ If the superproject doesn't have a default remote configured\n the superproject is its own authoritative upstream and the current\n working directory is used instead.\n +\n- is the relative location for the cloned submodule to\n-exist in the superproject. If does not exist, then the\n-submodule is created by cloning from the named URL. If does\n-exist and is already a valid Git repository, then this is added\n-to the changeset without cloning. This second form is provided\n-to ease creating a new submodule from scratch, and presumes\n-the user will later push the submodule to the given URL.\n+The optional argument is the relative location for the cloned\n+submodule to exist in the superproject. If is not given, the\n+canonical part of the source repository is used (\"repo\" for\n+\"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\"). If \n+exists and is already a valid Git repository, then it is staged\n+for commit without cloning. The is also used as the submodule's\n+logical name in its configuration entries unless `--name` is used\n+to specify a logical name.\n +\n-In either case, the given URL is recorded into .gitmodules for\n-use by subsequent users cloning the superproject. If the URL is\n-given relative to the superproject's repository, the presumption\n-is the superproject and submodule repositories will be kept\n-together in the same relative location, and only the\n-superproject's URL needs to be provided: git-submodule will correctly\n-locate the submodule using the relative URL in .gitmodules.\n+The given URL is recorded into `.gitmodules` for use by subsequent users\n+cloning the superproject. If the URL is given relative to the\n+superproject's repository, the presumption is the superproject and\n+submodule repositories will be kept together in the same relative\n+location, and only the superproject's URL needs to be provided.\n+git-submodule will correctly locate the submodule using the relative\n+URL in `.gitmodules`.\n \n status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n@@ -123,7 +116,7 @@ too (and can also report changes to a submodule's work tree).\n init [--] [...]::\n \tInitialize the submodules recorded in the index (which were\n \tadded and committed elsewhere) by setting `submodule.$name.url`\n-\tin .git/config. It uses the same setting from .gitmodules as\n+\tin .git/config. It uses the same setting from `.gitmodules` as\n \ta template. If the URL is relative, it will be resolved using\n \tthe default remote. If there is no default remote, the current\n \trepository will be assumed to be upstream.\n@@ -197,7 +190,7 @@ configuration variable:\n \tnone;; the submodule is not updated.\n \n If the submodule is not yet initialized, and you just want to use the\n-setting as stored in .gitmodules, you can automatically initialize the\n+setting as stored in `.gitmodules`, you can automatically initialize the\n submodule with the `--init` option.\n \n If `--recursive` is specified, this command will recurse into the\n@@ -220,7 +213,7 @@ foreach [--recursive] ::\n \tEvaluates an arbitrary shell command in each checked out submodule.\n \tThe command has access to the variables $name, $path, $sha1 and\n \t$toplevel:\n-\t$name is the name of the relevant submodule section in .gitmodules,\n+\t$name is the name of the relevant submodule section in `.gitmodules`,\n \t$path is the name of the submodule directory relative to the\n \tsuperproject, $sha1 is the commit as recorded in the superproject,\n \tand $toplevel is the absolute path to the top-level of the superproject.\n@@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse HEAD`'\n \n sync [--recursive] [--] [...]::\n \tSynchronizes submodules' remote URL configuration setting\n-\tto the value specified in .gitmodules. It will only affect those\n+\tto the value specified in `.gitmodules`. It will only affect those\n \tsubmodules which already have a URL entry in .git/config (that is the\n \tcase when they are initialized or freshly added). This is useful when\n \tsubmodule URLs change upstream and you need to update your local\n@@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.\n --[no-]recommend-shallow::\n \tThis option is only valid for the update command.\n \tThe initial clone of a submodule will use the recommended\n-\t`submodule..shallow` as provided by the .gitmodules file\n+\t`submodule..shallow` as provided by the `.gitmodules` file\n \tby default. To ignore the suggestions use `--no-recommend-shallow`.\n \n -j ::\n@@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.\n \n FILES\n -----\n-When initializing submodules, a .gitmodules file in the top-level directory\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 `$GIT_DIR/config`. The key\n to each submodule url is \"submodule.$name.url\". See linkgit:gitmodules[5]\n\n--\nhttps://github.com/git/git/pull/377\n"},{"id":"322968","messageId":"xmqqr2ybkfj7.fsf@gitster.mtv.corp.google.com","threadId":"46206","inReplyTo":"0102015ccdb6695c-7a8b1188-5bbe-43d1-8a8f-913c006c2474-000000@eu-west-1.amazonses.com","subject":"Re: [PATCH/FINAL] Documentation/git-submodule: cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-06-22T19:07:08Z","receivedAt":"2017-06-22T19:07:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kaartic Sivaraam writes:\n\n> The \"add\" section for 'git-submodule' is redundant in\n> its description and the short synopsis line. Fix it.\n>\n> Remove the redundant mentioning of the 'repository' argument\n> being mandatory.\n>\n> The text is hard to read because of back-references, so remove\n> those.\n>\n> Replace the word \"humanish\" by \"canonical\" as that conveys better\n> what we do to guess the path.\n>\n> While at it, quote all occurrences of '.gitmodules' as that is an\n> important file in the submodule context, also link to it on its\n> first mention.\n>\n> Helped-by: Stefan Beller \n> Signed-off-by: Kaartic Sivaraam \n> ---\n\nStefan, do you want to add a Reviewed-by: to this one? I've scanned\nit over and overall it looked OK (iow I didn't find anything worth\ncomplaining about).\n\nThanks.\n\n> Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------------------\n> 1 file changed, 21 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 74bc6200d564c..6e07bade39a7c 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -63,14 +63,6 @@ add [-b ] [-f|--force] [--name ] [--reference ] [--dep\n> \tto the changeset to be committed next to the current\n> \tproject: the current project is termed the \"superproject\".\n> +\n> -This requires at least one argument: . The optional\n> -argument is the relative location for the cloned submodule\n> -to exist in the superproject. If 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 is also used as the submodule's logical name in its\n> -configuration entries unless `--name` is used to specify a logical name.\n> -+\n> is the URL of the new submodule's origin repository.\n> This may be either an absolute URL, or (if it begins with ./\n> or ../), the location relative to the superproject's default remote\n> @@ -87,21 +79,22 @@ If the superproject doesn't have a default remote configured\n> the superproject is its own authoritative upstream and the current\n> working directory is used instead.\n> +\n> - is the relative location for the cloned submodule to\n> -exist in the superproject. If does not exist, then the\n> -submodule is created by cloning from the named URL. If does\n> -exist and is already a valid Git repository, then this is added\n> -to the changeset without cloning. This second form is provided\n> -to ease creating a new submodule from scratch, and presumes\n> -the user will later push the submodule to the given URL.\n> +The optional argument is the relative location for the cloned\n> +submodule to exist in the superproject. If is not given, the\n> +canonical part of the source repository is used (\"repo\" for\n> +\"/path/to/repo.git\" and \"foo\" for \"host.xz:foo/.git\"). If \n> +exists and is already a valid Git repository, then it is staged\n> +for commit without cloning. The is also used as the submodule's\n> +logical name in its configuration entries unless `--name` is used\n> +to specify a logical name.\n> +\n> -In either case, the given URL is recorded into .gitmodules for\n> -use by subsequent users cloning the superproject. If the URL is\n> -given relative to the superproject's repository, the presumption\n> -is the superproject and submodule repositories will be kept\n> -together in the same relative location, and only the\n> -superproject's URL needs to be provided: git-submodule will correctly\n> -locate the submodule using the relative URL in .gitmodules.\n> +The given URL is recorded into `.gitmodules` for use by subsequent users\n> +cloning the superproject. If the URL is given relative to the\n> +superproject's repository, the presumption is the superproject and\n> +submodule repositories will be kept together in the same relative\n> +location, and only the superproject's URL needs to be provided.\n> +git-submodule will correctly locate the submodule using the relative\n> +URL in `.gitmodules`.\n> \n> status [--cached] [--recursive] [--] [...]::\n> \tShow the status of the submodules. This will print the SHA-1 of the\n> @@ -123,7 +116,7 @@ too (and can also report changes to a submodule's work tree).\n> init [--] [...]::\n> \tInitialize the submodules recorded in the index (which were\n> \tadded and committed elsewhere) by setting `submodule.$name.url`\n> -\tin .git/config. It uses the same setting from .gitmodules as\n> +\tin .git/config. It uses the same setting from `.gitmodules` as\n> \ta template. If the URL is relative, it will be resolved using\n> \tthe default remote. If there is no default remote, the current\n> \trepository will be assumed to be upstream.\n> @@ -197,7 +190,7 @@ configuration variable:\n> \tnone;; the submodule is not updated.\n> \n> If the submodule is not yet initialized, and you just want to use the\n> -setting as stored in .gitmodules, you can automatically initialize the\n> +setting as stored in `.gitmodules`, you can automatically initialize the\n> submodule with the `--init` option.\n> \n> If `--recursive` is specified, this command will recurse into the\n> @@ -220,7 +213,7 @@ foreach [--recursive] ::\n> \tEvaluates an arbitrary shell command in each checked out submodule.\n> \tThe command has access to the variables $name, $path, $sha1 and\n> \t$toplevel:\n> -\t$name is the name of the relevant submodule section in .gitmodules,\n> +\t$name is the name of the relevant submodule section in `.gitmodules`,\n> \t$path is the name of the submodule directory relative to the\n> \tsuperproject, $sha1 is the commit as recorded in the superproject,\n> \tand $toplevel is the absolute path to the top-level of the superproject.\n> @@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse HEAD`'\n> \n> sync [--recursive] [--] [...]::\n> \tSynchronizes submodules' remote URL configuration setting\n> -\tto the value specified in .gitmodules. It will only affect those\n> +\tto the value specified in `.gitmodules`. It will only affect those\n> \tsubmodules which already have a URL entry in .git/config (that is the\n> \tcase when they are initialized or freshly added). This is useful when\n> \tsubmodule URLs change upstream and you need to update your local\n> @@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.\n> --[no-]recommend-shallow::\n> \tThis option is only valid for the update command.\n> \tThe initial clone of a submodule will use the recommended\n> -\t`submodule..shallow` as provided by the .gitmodules file\n> +\t`submodule..shallow` as provided by the `.gitmodules` file\n> \tby default. To ignore the suggestions use `--no-recommend-shallow`.\n> \n> -j ::\n> @@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.\n> \n> FILES\n> -----\n> -When initializing submodules, a .gitmodules file in the top-level directory\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 `$GIT_DIR/config`. The key\n> to each submodule url is \"submodule.$name.url\". See linkgit:gitmodules[5]\n>\n> --\n> https://github.com/git/git/pull/377\n"},{"id":"322969","messageId":"CAGZ79kYAJR7WXn9p1tGXTWTw9V4kpBX9g_W2_dy0AE9OLFPcvw@mail.gmail.com","threadId":"46206","inReplyTo":"xmqqr2ybkfj7.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH/FINAL] Documentation/git-submodule: cleanup","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-06-22T19:13:42Z","receivedAt":"2017-06-22T19:13:49Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Thu, Jun 22, 2017 at 12:07 PM, Junio C Hamano wrote:\n> Kaartic Sivaraam writes:\n>\n>> The \"add\" section for 'git-submodule' is redundant in\n>> its description and the short synopsis line. Fix it.\n>>\n>> Remove the redundant mentioning of the 'repository' argument\n>> being mandatory.\n>>\n>> The text is hard to read because of back-references, so remove\n>> those.\n>>\n>> Replace the word \"humanish\" by \"canonical\" as that conveys better\n>> what we do to guess the path.\n>>\n>> While at it, quote all occurrences of '.gitmodules' as that is an\n>> important file in the submodule context, also link to it on its\n>> first mention.\n>>\n>> Helped-by: Stefan Beller \n>> Signed-off-by: Kaartic Sivaraam \n>> ---\n>\n> Stefan, do you want to add a Reviewed-by: to this one? I've scanned\n> it over and overall it looked OK (iow I didn't find anything worth\n> complaining about).\n\nI found it a pleasant read, thanks.\n\nAs all occurrences of '.gitmodules' are touched, I suspect we will run into\na conflict with sb/submodule-doc, such that I will rebase on top of this.\n\nThanks,\nStefan\n"}]}