| Message ID | d8785cdd01503f2a7b9a6fbc19105c41a9a04046.1549965172.git.liu.denton@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Document git-submodule's default behavior | expand |
Denton Liu <liu.denton@gmail.com> writes: > This patch documents the default behavior of submodule if no subcommands > are given, similar to how remote documents it in both git-remote.txt and > in its usage output. Let's stop saying "This patch does this, this patch does that". Instead (1) state what you think is wrong with the status quo in the present tense, (2) describe what the right approach to make it better is and why, and (3) order the codebase to "be like so" to make that happen. Often (1) or (2) can be omitted when they are obvious from (3), but be mindful to others---the "obviousness" you may feel may come from your staring the problem longer and thinking about it deeper than the readers of your patch. When in doubt, err on the side of over-clarity. The SYNOPSIS section for 'git submodule' does not say what the command does when given no subcommand. Document it. does (1)+(3), which I think is sufficient. > Signed-off-by: Denton Liu <liu.denton@gmail.com> > --- > Documentation/git-submodule.txt | 4 ++++ > git-submodule.sh | 3 ++- > 2 files changed, 6 insertions(+), 1 deletion(-) > > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt > index 65a952fb96..2fdf9f4cf3 100644 > --- a/Documentation/git-submodule.txt > +++ b/Documentation/git-submodule.txt > @@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules > SYNOPSIS > -------- > [verse] > +'git submodule' [--quiet] [--cached] > 'git submodule' [--quiet] 'add' [<options>] [--] <repository> [<path>] > 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [<path>...] > 'git submodule' [--quiet] 'init' [--] [<path>...] > @@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7]. > > COMMANDS > -------- > +With no arguments, the default command is 'status'. Several subcommands are > +available to perform operations on the submodules. I am not sure if "default is status" is really true. $ git submodule status --recursive $ git submodule --recursive usage: git submodule [--quiet] ... or: ... $ git submodule -- sha1collisiondetection usage: git submodule [--quiet] ... or: ... If 'status' were truly the default, wouldn't the form without any subcommand take any option and parameter the 'status' subcommand would accept? > diff --git a/git-submodule.sh b/git-submodule.sh > index 5e608f8bad..1ccc758e79 100755 > --- a/git-submodule.sh > +++ b/git-submodule.sh > @@ -5,7 +5,8 @@ > # Copyright (c) 2007 Lars Hjemli > > dashless=$(basename "$0" | sed -e 's/-/ /') > -USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] > +USAGE="[--quiet] [--cached] > + or: $dashless [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] > or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] > or: $dashless [--quiet] init [--] [<path>...] > or: $dashless [--quiet] deinit [-f|--force] (--all| [--] <path>...)
On Wed, Feb 13, 2019 at 10:39:48AM -0800, Junio C Hamano wrote: > Denton Liu <liu.denton@gmail.com> writes: > > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt > > index 65a952fb96..2fdf9f4cf3 100644 > > --- a/Documentation/git-submodule.txt > > +++ b/Documentation/git-submodule.txt > > @@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules > > SYNOPSIS > > -------- > > [verse] > > +'git submodule' [--quiet] [--cached] > > 'git submodule' [--quiet] 'add' [<options>] [--] <repository> [<path>] > > 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [<path>...] > > 'git submodule' [--quiet] 'init' [--] [<path>...] > > @@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7]. > > > > COMMANDS > > -------- > > +With no arguments, the default command is 'status'. Several subcommands are > > +available to perform operations on the submodules. > > I am not sure if "default is status" is really true. > > $ git submodule status --recursive > $ git submodule --recursive > usage: git submodule [--quiet] ... > or: ... > $ git submodule -- sha1collisiondetection > usage: git submodule [--quiet] ... > or: ... > > If 'status' were truly the default, wouldn't the form without any > subcommand take any option and parameter the 'status' subcommand > would accept? This is very similar to git-remote. Its default command is 'show' but doing something like 'git remote -n' fails, even though 'git remote show -n' succeeds. Would it make sense to revise this back to With no arguments, shows the status of existing submodules. which was the phrasing I used in v1? (If this is the case, I'd also like to drop the first patch of this series.) Thanks, Denton
Denton Liu <liu.denton@gmail.com> writes: >> > +With no arguments, the default command is 'status'. Several subcommands are >> > +available to perform operations on the submodules. >> >> I am not sure if "default is status" is really true. >> >> $ git submodule status --recursive >> $ git submodule --recursive >> usage: git submodule [--quiet] ... >> or: ... >> $ git submodule -- sha1collisiondetection >> usage: git submodule [--quiet] ... >> or: ... >> >> If 'status' were truly the default, wouldn't the form without any >> subcommand take any option and parameter the 'status' subcommand >> would accept? > > This is very similar to git-remote. Its default command is 'show' but > doing something like 'git remote -n' fails, even though > 'git remote show -n' succeeds. > > Would it make sense to revise this back to > > With no arguments, shows the status of existing submodules. > > which was the phrasing I used in v1? (If this is the case, I'd also like > to drop the first patch of this series.) It certainly would avoid spreading misinformation to the readers by technically more correct ;-). I wasn't paying close attention to the earlier round's review, but was there something specific that we wanted to achieve by mentioning "by default we do this"? If not, the "with no arguments ..." you have in your response is concise, readable, and informative and is a good description, I think. Thanks.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 65a952fb96..2fdf9f4cf3 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,6 +9,7 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] +'git submodule' [--quiet] [--cached] 'git submodule' [--quiet] 'add' [<options>] [--] <repository> [<path>] 'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] 'init' [--] [<path>...] @@ -28,6 +29,9 @@ For more information about submodules, see linkgit:gitsubmodules[7]. COMMANDS -------- +With no arguments, the default command is 'status'. Several subcommands are +available to perform operations on the submodules. + add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current diff --git a/git-submodule.sh b/git-submodule.sh index 5e608f8bad..1ccc758e79 100755 --- a/git-submodule.sh +++ b/git-submodule.sh @@ -5,7 +5,8 @@ # Copyright (c) 2007 Lars Hjemli dashless=$(basename "$0" | sed -e 's/-/ /') -USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] +USAGE="[--quiet] [--cached] + or: $dashless [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] or: $dashless [--quiet] init [--] [<path>...] or: $dashless [--quiet] deinit [-f|--force] (--all| [--] <path>...)
This patch documents the default behavior of submodule if no subcommands are given, similar to how remote documents it in both git-remote.txt and in its usage output. Signed-off-by: Denton Liu <liu.denton@gmail.com> --- Documentation/git-submodule.txt | 4 ++++ git-submodule.sh | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-)