[PATCH] git-submodule.txt: document default behavior

[PATCH] git-submodule.txt: document default behavior

[Denton Liu]

This patch documents the default behavior of git-submodule if no
subcommands are given, similar to how git-remote.txt documents it.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-submodule.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index ba3c4df550..9bc98da154 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -28,6 +28,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].
 
 COMMANDS
 --------
+With no arguments, shows the status of existing submodules.  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
-- 
2.20.1.530.g88cfe87ec3

Re: [PATCH] git-submodule.txt: document default behavior

[Duy Nguyen]

On Tue, Feb 12, 2019 at 11:04 AM Denton Liu <liu.denton@gmail.com> wrote:
>
> This patch documents the default behavior of git-submodule if no
> subcommands are given, similar to how git-remote.txt documents it.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/git-submodule.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index ba3c4df550..9bc98da154 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -28,6 +28,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].
>
>  COMMANDS
>  --------
> +With no arguments, shows the status of existing submodules.  Several

Maybe just "The default command is 'status'" and let the user read
that subcommand for more info.

> +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
> --
> 2.20.1.530.g88cfe87ec3
>


-- 
Duy

[PATCH v2 0/3] Document git-submodule's default behavior

[Denton Liu]

Thanks for the suggestion, Duy.

While I was fixing that up, I noticed a few other discrepancies so I
decided to fix those up too.

Changes since v1:

* Incorporate Duy's suggestion of "The default command is '...'"
* Fix additional discrepancies between git-remote and git-submodule (on the
  submodule side)


Denton Liu (3):
  git-remote.txt: be specific about default behavior
  git-submodule.txt: make subcommands underlined
  submodule: document default behavior

 Documentation/git-remote.txt    |  4 ++--
 Documentation/git-submodule.txt | 22 +++++++++++++---------
 git-submodule.sh                |  3 ++-
 3 files changed, 17 insertions(+), 12 deletions(-)

-- 
2.20.1.522.gd8785cdd01

[PATCH v2 1/3] git-remote.txt: be specific about default behavior

[Denton Liu]

Instead of beating around the bush, we directly specify the subcommand
that is called by default when none are provided. This way, a user will
know where to look for more information.
---
 Documentation/git-remote.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 0cad37fb81..a2e685818b 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -41,8 +41,8 @@ OPTIONS
 COMMANDS
 --------
 
-With no arguments, shows a list of existing remotes.  Several
-subcommands are available to perform operations on the remotes.
+With no arguments, the default command is 'show'.  Several subcommands are
+available to perform operations on the remotes.
 
 'add'::
 
-- 
2.20.1.522.gd8785cdd01

[PATCH v2 2/3] git-submodule.txt: make subcommands underlined

[Denton Liu]

In git-remote.txt, the subcommands are underlined. Following that, we
also underline the subcommands in git-submodule.txt.
---
 Documentation/git-submodule.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index ba3c4df550..65a952fb96 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,15 +9,15 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
-'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
-'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
-'git submodule' [--quiet] update [<options>] [--] [<path>...]
-'git submodule' [--quiet] summary [<options>] [--] [<path>...]
-'git submodule' [--quiet] foreach [--recursive] <command>
-'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
-'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
+'git submodule' [--quiet] 'add' [<options>] [--] <repository> [<path>]
+'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [<path>...]
+'git submodule' [--quiet] 'init' [--] [<path>...]
+'git submodule' [--quiet] 'deinit' [-f|--force] (--all|[--] <path>...)
+'git submodule' [--quiet] 'update' [<options>] [--] [<path>...]
+'git submodule' [--quiet] 'summary' [<options>] [--] [<path>...]
+'git submodule' [--quiet] 'foreach' [--recursive] <command>
+'git submodule' [--quiet] 'sync' [--recursive] [--] [<path>...]
+'git submodule' [--quiet] 'absorbgitdirs' [--] [<path>...]
 
 
 DESCRIPTION
-- 
2.20.1.522.gd8785cdd01

[PATCH v2 3/3] submodule: document default behavior

[Denton Liu]

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(-)

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>...)
-- 
2.20.1.522.gd8785cdd01

Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined

[Denton Liu]

On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
> In git-remote.txt, the subcommands are underlined. Following that, we
> also underline the subcommands in git-submodule.txt.

I'd like to retract this patch. I realised that between git-remote,
git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty
inconsistent between whether it's formatted with the underline or not.

Also, I missed the underlining of the subcommands in the body of the
document.

But if someone thinks that unifying the formatting is a worthwhile
pursuit, I'd be happy to reroll this patchset to include this fix.

Thanks,

Denton

Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined

[Duy Nguyen]

On Wed, Feb 13, 2019 at 3:15 PM Denton Liu <liu.denton@gmail.com> wrote:
>
> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
> > In git-remote.txt, the subcommands are underlined. Following that, we
> > also underline the subcommands in git-submodule.txt.
>
> I'd like to retract this patch. I realised that between git-remote,
> git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty
> inconsistent between whether it's formatted with the underline or not.
>
> Also, I missed the underlining of the subcommands in the body of the
> document.
>
> But if someone thinks that unifying the formatting is a worthwhile
> pursuit, I'd be happy to reroll this patchset to include this fix.

Making documents look consistent is always good, I think. If you want
to do this, maybe have a look at the "Writing Documentation" section
in CodingGuidelines and add a note there too, about quoting subcommand
names.
-- 
Duy

Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
>> In git-remote.txt, the subcommands are underlined. Following that, we
>> also underline the subcommands in git-submodule.txt.
>
> I'd like to retract this patch. I realised that between git-remote,
> git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty
> inconsistent between whether it's formatted with the underline or not.
>
> Also, I missed the underlining of the subcommands in the body of the
> document.

I actually do not think using '<emph>' inside the SYNOPSIS section
is such a great idea to begin with.  We do want `<literal>` mark-up
in the body text to tell the users that it is something they need to
type literally (as opposed to what they can substitute with their
own).

In any case, consistent mark-up in the documentation is good.  But
you would probably want to make it a separate series, either a
preparatory one before real content changes are made, or a cleanup
one after.

Thanks.

Re: [PATCH v2 3/3] submodule: document default behavior

[Junio C Hamano]

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>...)

Re: [PATCH v2 3/3] submodule: document default behavior

[Denton Liu]

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

Re: [PATCH v2 3/3] submodule: document default behavior

[Junio C Hamano]

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.

[PATCH v3 0/1] Document git-submodule's default behavior

[Denton Liu]

Thanks for the review, Junio.

Changes since v1:

* Incorporate Duy's suggestion of "The default command is '...'"
* Fix additional discrepancies between git-remote and git-submodule (on the
  submodule side)

Changes since v2:

* Revert "The default command is '...'" back to original text
* Drop "git-remote.txt: be specific about default behavior" as a
  consequence of the above
* Drop "git-submodule.txt: make subcommands underlined" as this was
  unwanted

Denton Liu (1):
  submodule: document default behavior

 Documentation/git-submodule.txt | 4 ++++
 git-submodule.sh                | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

-- 
2.20.1.522.gd8785cdd01

[PATCH v3 1/1] submodule: document default behavior

[Denton Liu]

submodule's default behavior wasn't documented in both git-submodule.txt
and in the usage text of git-submodule. Document the default behavior
similar to how git-remote does it.

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 ba3c4df550..2794e29780 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, shows the status of existing submodules.  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>...)
-- 
2.20.1.522.gd8785cdd01