{"thread":{"id":"50476","subject":"[PATCH] git-submodule.txt: document default behavior","startedAt":"2019-02-12T04:03:41Z","lastAt":"2019-02-15T09:26:53Z","messageCount":14,"participants":["Denton Liu","Duy Nguyen","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"369125","messageId":"0b62f65a8016c41b96aa6caead366e1ed9dda333.1549944164.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":null,"subject":"[PATCH] git-submodule.txt: document default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-12T04:03:35Z","receivedAt":"2019-02-12T04:03:41Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"This patch documents the default behavior of git-submodule if no\nsubcommands are given, similar to how git-remote.txt documents it.\n\nSigned-off-by: Denton Liu \n---\n Documentation/git-submodule.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ba3c4df550..9bc98da154 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -28,6 +28,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n \n COMMANDS\n --------\n+With no arguments, shows the status of existing submodules. Several\n+subcommands are available to perform operations on the submodules.\n+\n add [-b ] [-f|--force] [--name ] [--reference ] [--depth ] [--] []::\n \tAdd the given repository as a submodule at the given path\n \tto the changeset to be committed next to the current\n-- \n2.20.1.530.g88cfe87ec3\n\n"},{"id":"369127","messageId":"CACsJy8ADLyog0ntfij+MUhPXHZfK-xQnnQPd5pvapttZQ9ZZ5w@mail.gmail.com","threadId":"50476","inReplyTo":"0b62f65a8016c41b96aa6caead366e1ed9dda333.1549944164.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-submodule.txt: document default behavior","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-02-12T05:33:11Z","receivedAt":"2019-02-12T05:33:40Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Feb 12, 2019 at 11:04 AM Denton Liu wrote:\n>\n> This patch documents the default behavior of git-submodule if no\n> subcommands are given, similar to how git-remote.txt documents it.\n>\n> Signed-off-by: Denton Liu \n> ---\n> Documentation/git-submodule.txt | 3 +++\n> 1 file changed, 3 insertions(+)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index ba3c4df550..9bc98da154 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -28,6 +28,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n>\n> COMMANDS\n> --------\n> +With no arguments, shows the status of existing submodules. Several\n\nMaybe just \"The default command is 'status'\" and let the user read\nthat subcommand for more info.\n\n> +subcommands are available to perform operations on the submodules.\n> +\n> add [-b ] [-f|--force] [--name ] [--reference ] [--depth ] [--] []::\n> Add the given repository as a submodule at the given path\n> to the changeset to be committed next to the current\n> --\n> 2.20.1.530.g88cfe87ec3\n>\n\n\n-- \nDuy\n"},{"id":"369136","messageId":"cover.1549965172.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"0b62f65a8016c41b96aa6caead366e1ed9dda333.1549944164.git.liu.denton@gmail.com","subject":"[PATCH v2 0/3] Document git-submodule's default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-12T09:56:05Z","receivedAt":"2019-02-12T09:56:11Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Thanks for the suggestion, Duy.\n\nWhile I was fixing that up, I noticed a few other discrepancies so I\ndecided to fix those up too.\n\nChanges since v1:\n\n* Incorporate Duy's suggestion of \"The default command is '...'\"\n* Fix additional discrepancies between git-remote and git-submodule (on the\n submodule side)\n\n\nDenton Liu (3):\n git-remote.txt: be specific about default behavior\n git-submodule.txt: make subcommands underlined\n submodule: document default behavior\n\n Documentation/git-remote.txt | 4 ++--\n Documentation/git-submodule.txt | 22 +++++++++++++---------\n git-submodule.sh | 3 ++-\n 3 files changed, 17 insertions(+), 12 deletions(-)\n\n-- \n2.20.1.522.gd8785cdd01\n\n"},{"id":"369137","messageId":"7e7e0dde0495e105bb717418745cc24edd051887.1549965172.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"cover.1549965172.git.liu.denton@gmail.com","subject":"[PATCH v2 1/3] git-remote.txt: be specific about default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-12T09:56:09Z","receivedAt":"2019-02-12T09:56:13Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Instead of beating around the bush, we directly specify the subcommand\nthat is called by default when none are provided. This way, a user will\nknow where to look for more information.\n---\n Documentation/git-remote.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 0cad37fb81..a2e685818b 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -41,8 +41,8 @@ OPTIONS\n COMMANDS\n --------\n \n-With no arguments, shows a list of existing remotes. Several\n-subcommands are available to perform operations on the remotes.\n+With no arguments, the default command is 'show'. Several subcommands are\n+available to perform operations on the remotes.\n \n 'add'::\n \n-- \n2.20.1.522.gd8785cdd01\n\n"},{"id":"369138","messageId":"b0c124d022bfa9a0bbe0c9494df24780b67c8a08.1549965172.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"cover.1549965172.git.liu.denton@gmail.com","subject":"[PATCH v2 2/3] git-submodule.txt: make subcommands underlined","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-12T09:56:11Z","receivedAt":"2019-02-12T09:56:16Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"In git-remote.txt, the subcommands are underlined. Following that, we\nalso underline the subcommands in git-submodule.txt.\n---\n Documentation/git-submodule.txt | 18 +++++++++---------\n 1 file changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ba3c4df550..65a952fb96 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -9,15 +9,15 @@ git-submodule - Initialize, update or inspect submodules\n SYNOPSIS\n --------\n [verse]\n-'git submodule' [--quiet] add [] [--] []\n-'git submodule' [--quiet] status [--cached] [--recursive] [--] [...]\n-'git submodule' [--quiet] init [--] [...]\n-'git submodule' [--quiet] deinit [-f|--force] (--all|[--] ...)\n-'git submodule' [--quiet] update [] [--] [...]\n-'git submodule' [--quiet] summary [] [--] [...]\n-'git submodule' [--quiet] foreach [--recursive] \n-'git submodule' [--quiet] sync [--recursive] [--] [...]\n-'git submodule' [--quiet] absorbgitdirs [--] [...]\n+'git submodule' [--quiet] 'add' [] [--] []\n+'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [...]\n+'git submodule' [--quiet] 'init' [--] [...]\n+'git submodule' [--quiet] 'deinit' [-f|--force] (--all|[--] ...)\n+'git submodule' [--quiet] 'update' [] [--] [...]\n+'git submodule' [--quiet] 'summary' [] [--] [...]\n+'git submodule' [--quiet] 'foreach' [--recursive] \n+'git submodule' [--quiet] 'sync' [--recursive] [--] [...]\n+'git submodule' [--quiet] 'absorbgitdirs' [--] [...]\n \n \n DESCRIPTION\n-- \n2.20.1.522.gd8785cdd01\n\n"},{"id":"369139","messageId":"d8785cdd01503f2a7b9a6fbc19105c41a9a04046.1549965172.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"cover.1549965172.git.liu.denton@gmail.com","subject":"[PATCH v2 3/3] submodule: document default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-12T09:56:13Z","receivedAt":"2019-02-12T09:56:18Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"This patch documents the default behavior of submodule if no subcommands\nare given, similar to how remote documents it in both git-remote.txt and\nin its usage output.\n\nSigned-off-by: Denton Liu \n---\n Documentation/git-submodule.txt | 4 ++++\n git-submodule.sh | 3 ++-\n 2 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 65a952fb96..2fdf9f4cf3 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules\n SYNOPSIS\n --------\n [verse]\n+'git submodule' [--quiet] [--cached]\n 'git submodule' [--quiet] 'add' [] [--] []\n 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [...]\n 'git submodule' [--quiet] 'init' [--] [...]\n@@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n \n COMMANDS\n --------\n+With no arguments, the default command is 'status'. Several subcommands are\n+available to perform operations on the submodules.\n+\n add [-b ] [-f|--force] [--name ] [--reference ] [--depth ] [--] []::\n \tAdd the given repository as a submodule at the given path\n \tto the changeset to be committed next to the current\ndiff --git a/git-submodule.sh b/git-submodule.sh\nindex 5e608f8bad..1ccc758e79 100755\n--- a/git-submodule.sh\n+++ b/git-submodule.sh\n@@ -5,7 +5,8 @@\n # Copyright (c) 2007 Lars Hjemli\n \n dashless=$(basename \"$0\" | sed -e 's/-/ /')\n-USAGE=\"[--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n+USAGE=\"[--quiet] [--cached]\n+ or: $dashless [--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n or: $dashless [--quiet] status [--cached] [--recursive] [--] [...]\n or: $dashless [--quiet] init [--] [...]\n or: $dashless [--quiet] deinit [-f|--force] (--all| [--] ...)\n-- \n2.20.1.522.gd8785cdd01\n\n"},{"id":"369210","messageId":"20190213081518.GA21926@archbookpro.localdomain","threadId":"50476","inReplyTo":"b0c124d022bfa9a0bbe0c9494df24780b67c8a08.1549965172.git.liu.denton@gmail.com","subject":"Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-13T08:15:18Z","receivedAt":"2019-02-13T08:15:24Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:\n> In git-remote.txt, the subcommands are underlined. Following that, we\n> also underline the subcommands in git-submodule.txt.\n\nI'd like to retract this patch. I realised that between git-remote,\ngit-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty\ninconsistent between whether it's formatted with the underline or not.\n\nAlso, I missed the underlining of the subcommands in the body of the\ndocument.\n\nBut if someone thinks that unifying the formatting is a worthwhile\npursuit, I'd be happy to reroll this patchset to include this fix.\n\nThanks,\n\nDenton\n"},{"id":"369215","messageId":"CACsJy8A2M2vc36OLN9jMt3tPq+AwNquyxjrdQXQ7zNZ8pAjTSQ@mail.gmail.com","threadId":"50476","inReplyTo":"20190213081518.GA21926@archbookpro.localdomain","subject":"Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-02-13T09:55:50Z","receivedAt":"2019-02-13T09:56:20Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Wed, Feb 13, 2019 at 3:15 PM Denton Liu wrote:\n>\n> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:\n> > In git-remote.txt, the subcommands are underlined. Following that, we\n> > also underline the subcommands in git-submodule.txt.\n>\n> I'd like to retract this patch. I realised that between git-remote,\n> git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty\n> inconsistent between whether it's formatted with the underline or not.\n>\n> Also, I missed the underlining of the subcommands in the body of the\n> document.\n>\n> But if someone thinks that unifying the formatting is a worthwhile\n> pursuit, I'd be happy to reroll this patchset to include this fix.\n\nMaking documents look consistent is always good, I think. If you want\nto do this, maybe have a look at the \"Writing Documentation\" section\nin CodingGuidelines and add a note there too, about quoting subcommand\nnames.\n-- \nDuy\n"},{"id":"369245","messageId":"xmqq4l97czhu.fsf@gitster-ct.c.googlers.com","threadId":"50476","inReplyTo":"20190213081518.GA21926@archbookpro.localdomain","subject":"Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-02-13T18:30:37Z","receivedAt":"2019-02-13T18:30:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:\n>> In git-remote.txt, the subcommands are underlined. Following that, we\n>> also underline the subcommands in git-submodule.txt.\n>\n> I'd like to retract this patch. I realised that between git-remote,\n> git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty\n> inconsistent between whether it's formatted with the underline or not.\n>\n> Also, I missed the underlining of the subcommands in the body of the\n> document.\n\nI actually do not think using '' inside the SYNOPSIS section\nis such a great idea to begin with. We do want `` mark-up\nin the body text to tell the users that it is something they need to\ntype literally (as opposed to what they can substitute with their\nown).\n\nIn any case, consistent mark-up in the documentation is good. But\nyou would probably want to make it a separate series, either a\npreparatory one before real content changes are made, or a cleanup\none after.\n\nThanks.\n\n"},{"id":"369247","messageId":"xmqqzhqzbki3.fsf@gitster-ct.c.googlers.com","threadId":"50476","inReplyTo":"d8785cdd01503f2a7b9a6fbc19105c41a9a04046.1549965172.git.liu.denton@gmail.com","subject":"Re: [PATCH v2 3/3] submodule: document default behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-02-13T18:39:48Z","receivedAt":"2019-02-13T18:56:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n> This patch documents the default behavior of submodule if no subcommands\n> are given, similar to how remote documents it in both git-remote.txt and\n> in its usage output.\n\nLet's stop saying \"This patch does this, this patch does that\".\n\nInstead (1) state what you think is wrong with the status quo in the\npresent tense, (2) describe what the right approach to make it\nbetter is and why, and (3) order the codebase to \"be like so\" to\nmake that happen. Often (1) or (2) can be omitted when they are\nobvious from (3), but be mindful to others---the \"obviousness\" you\nmay feel may come from your staring the problem longer and thinking\nabout it deeper than the readers of your patch. When in doubt, err\non the side of over-clarity.\n\n The SYNOPSIS section for 'git submodule' does not say what the\n command does when given no subcommand. Document it.\n\ndoes (1)+(3), which I think is sufficient.\n\n> Signed-off-by: Denton Liu \n> ---\n> Documentation/git-submodule.txt | 4 ++++\n> git-submodule.sh | 3 ++-\n> 2 files changed, 6 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 65a952fb96..2fdf9f4cf3 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules\n> SYNOPSIS\n> --------\n> [verse]\n> +'git submodule' [--quiet] [--cached]\n> 'git submodule' [--quiet] 'add' [] [--] []\n> 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [...]\n> 'git submodule' [--quiet] 'init' [--] [...]\n> @@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n> \n> COMMANDS\n> --------\n> +With no arguments, the default command is 'status'. Several subcommands are\n> +available to perform operations on the submodules.\n\nI am not sure if \"default is status\" is really true.\n\n $ git submodule status --recursive\n $ git submodule --recursive\n usage: git submodule [--quiet] ...\n or: ...\n $ git submodule -- sha1collisiondetection\n usage: git submodule [--quiet] ...\n or: ...\n\nIf 'status' were truly the default, wouldn't the form without any\nsubcommand take any option and parameter the 'status' subcommand\nwould accept? \n\n> diff --git a/git-submodule.sh b/git-submodule.sh\n> index 5e608f8bad..1ccc758e79 100755\n> --- a/git-submodule.sh\n> +++ b/git-submodule.sh\n> @@ -5,7 +5,8 @@\n> # Copyright (c) 2007 Lars Hjemli\n> \n> dashless=$(basename \"$0\" | sed -e 's/-/ /')\n> -USAGE=\"[--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n> +USAGE=\"[--quiet] [--cached]\n> + or: $dashless [--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n> or: $dashless [--quiet] status [--cached] [--recursive] [--] [...]\n> or: $dashless [--quiet] init [--] [...]\n> or: $dashless [--quiet] deinit [-f|--force] (--all| [--] ...)\n"},{"id":"369300","messageId":"20190214072405.GA24259@archbookpro.localdomain","threadId":"50476","inReplyTo":"xmqqzhqzbki3.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v2 3/3] submodule: document default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-14T07:24:05Z","receivedAt":"2019-02-14T07:24:10Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"On Wed, Feb 13, 2019 at 10:39:48AM -0800, Junio C Hamano wrote:\n> Denton Liu writes:\n> > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> > index 65a952fb96..2fdf9f4cf3 100644\n> > --- a/Documentation/git-submodule.txt\n> > +++ b/Documentation/git-submodule.txt\n> > @@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules\n> > SYNOPSIS\n> > --------\n> > [verse]\n> > +'git submodule' [--quiet] [--cached]\n> > 'git submodule' [--quiet] 'add' [] [--] []\n> > 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [...]\n> > 'git submodule' [--quiet] 'init' [--] [...]\n> > @@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n> >\n> > COMMANDS\n> > --------\n> > +With no arguments, the default command is 'status'. Several subcommands are\n> > +available to perform operations on the submodules.\n>\n> I am not sure if \"default is status\" is really true.\n>\n> $ git submodule status --recursive\n> $ git submodule --recursive\n> usage: git submodule [--quiet] ...\n> or: ...\n> $ git submodule -- sha1collisiondetection\n> usage: git submodule [--quiet] ...\n> or: ...\n>\n> If 'status' were truly the default, wouldn't the form without any\n> subcommand take any option and parameter the 'status' subcommand\n> would accept?\n\nThis is very similar to git-remote. Its default command is 'show' but\ndoing something like 'git remote -n' fails, even though\n'git remote show -n' succeeds.\n\nWould it make sense to revise this back to\n\n\tWith no arguments, shows the status of existing submodules.\n\nwhich was the phrasing I used in v1? (If this is the case, I'd also like\nto drop the first patch of this series.)\n\nThanks,\n\nDenton\n"},{"id":"369319","messageId":"xmqqsgwq8dyb.fsf@gitster-ct.c.googlers.com","threadId":"50476","inReplyTo":"20190214072405.GA24259@archbookpro.localdomain","subject":"Re: [PATCH v2 3/3] submodule: document default behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-02-14T17:41:48Z","receivedAt":"2019-02-14T17:41:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n>> > +With no arguments, the default command is 'status'. Several subcommands are\n>> > +available to perform operations on the submodules.\n>>\n>> I am not sure if \"default is status\" is really true.\n>>\n>> $ git submodule status --recursive\n>> $ git submodule --recursive\n>> usage: git submodule [--quiet] ...\n>> or: ...\n>> $ git submodule -- sha1collisiondetection\n>> usage: git submodule [--quiet] ...\n>> or: ...\n>>\n>> If 'status' were truly the default, wouldn't the form without any\n>> subcommand take any option and parameter the 'status' subcommand\n>> would accept?\n>\n> This is very similar to git-remote. Its default command is 'show' but\n> doing something like 'git remote -n' fails, even though\n> 'git remote show -n' succeeds.\n>\n> Would it make sense to revise this back to\n>\n> \tWith no arguments, shows the status of existing submodules.\n>\n> which was the phrasing I used in v1? (If this is the case, I'd also like\n> to drop the first patch of this series.)\n\nIt certainly would avoid spreading misinformation to the readers by\ntechnically more correct ;-). I wasn't paying close attention to\nthe earlier round's review, but was there something specific that we\nwanted to achieve by mentioning \"by default we do this\"? If not,\nthe \"with no arguments ...\" you have in your response is concise,\nreadable, and informative and is a good description, I think.\n\nThanks.\n"},{"id":"369377","messageId":"cover.1550222580.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"cover.1549965172.git.liu.denton@gmail.com","subject":"[PATCH v3 0/1] Document git-submodule's default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-15T09:26:37Z","receivedAt":"2019-02-15T09:26:43Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Thanks for the review, Junio.\n\nChanges since v1:\n\n* Incorporate Duy's suggestion of \"The default command is '...'\"\n* Fix additional discrepancies between git-remote and git-submodule (on the\n submodule side)\n\nChanges since v2:\n\n* Revert \"The default command is '...'\" back to original text\n* Drop \"git-remote.txt: be specific about default behavior\" as a\n consequence of the above\n* Drop \"git-submodule.txt: make subcommands underlined\" as this was\n unwanted\n\nDenton Liu (1):\n submodule: document default behavior\n\n Documentation/git-submodule.txt | 4 ++++\n git-submodule.sh | 3 ++-\n 2 files changed, 6 insertions(+), 1 deletion(-)\n\n-- \n2.20.1.522.gd8785cdd01\n\n"},{"id":"369378","messageId":"bc9088f23c0e9d4feedf9b2cc47cf6e6c34cefb2.1550222580.git.liu.denton@gmail.com","threadId":"50476","inReplyTo":"cover.1550222580.git.liu.denton@gmail.com","subject":"[PATCH v3 1/1] submodule: document default behavior","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-02-15T09:26:41Z","receivedAt":"2019-02-15T09:26:53Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"submodule's default behavior wasn't documented in both git-submodule.txt\nand in the usage text of git-submodule. Document the default behavior\nsimilar to how git-remote does it.\n\nSigned-off-by: Denton Liu \n---\n Documentation/git-submodule.txt | 4 ++++\n git-submodule.sh | 3 ++-\n 2 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ba3c4df550..2794e29780 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules\n SYNOPSIS\n --------\n [verse]\n+'git submodule' [--quiet] [--cached]\n 'git submodule' [--quiet] add [] [--] []\n 'git submodule' [--quiet] status [--cached] [--recursive] [--] [...]\n 'git submodule' [--quiet] init [--] [...]\n@@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].\n \n COMMANDS\n --------\n+With no arguments, shows the status of existing submodules. Several\n+subcommands are available to perform operations on the submodules.\n+\n add [-b ] [-f|--force] [--name ] [--reference ] [--depth ] [--] []::\n \tAdd the given repository as a submodule at the given path\n \tto the changeset to be committed next to the current\ndiff --git a/git-submodule.sh b/git-submodule.sh\nindex 5e608f8bad..1ccc758e79 100755\n--- a/git-submodule.sh\n+++ b/git-submodule.sh\n@@ -5,7 +5,8 @@\n # Copyright (c) 2007 Lars Hjemli\n \n dashless=$(basename \"$0\" | sed -e 's/-/ /')\n-USAGE=\"[--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n+USAGE=\"[--quiet] [--cached]\n+ or: $dashless [--quiet] add [-b ] [-f|--force] [--name ] [--reference ] [--] []\n or: $dashless [--quiet] status [--cached] [--recursive] [--] [...]\n or: $dashless [--quiet] init [--] [...]\n or: $dashless [--quiet] deinit [-f|--force] (--all| [--] ...)\n-- \n2.20.1.522.gd8785cdd01\n\n"}]}