git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
* [PATCH] git-submodule.txt: document default behavior
@ 2019-02-12  4:03 Denton Liu
  2019-02-12  5:33 ` Duy Nguyen
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
  0 siblings, 2 replies; 14+ messages in thread
From: Denton Liu @ 2019-02-12  4:03 UTC (permalink / raw)
  To: git

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH] git-submodule.txt: document default behavior
  2019-02-12  4:03 [PATCH] git-submodule.txt: document default behavior Denton Liu
@ 2019-02-12  5:33 ` Duy Nguyen
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
  1 sibling, 0 replies; 14+ messages in thread
From: Duy Nguyen @ 2019-02-12  5:33 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v2 0/3] Document git-submodule's default behavior
  2019-02-12  4:03 [PATCH] git-submodule.txt: document default behavior Denton Liu
  2019-02-12  5:33 ` Duy Nguyen
@ 2019-02-12  9:56 ` " Denton Liu
  2019-02-12  9:56   ` [PATCH v2 1/3] git-remote.txt: be specific about " Denton Liu
                     ` (3 more replies)
  1 sibling, 4 replies; 14+ messages in thread
From: Denton Liu @ 2019-02-12  9:56 UTC (permalink / raw)
  To: git; +Cc: pclouds

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v2 1/3] git-remote.txt: be specific about default behavior
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
@ 2019-02-12  9:56   ` " Denton Liu
  2019-02-12  9:56   ` [PATCH v2 2/3] git-submodule.txt: make subcommands underlined Denton Liu
                     ` (2 subsequent siblings)
  3 siblings, 0 replies; 14+ messages in thread
From: Denton Liu @ 2019-02-12  9:56 UTC (permalink / raw)
  To: git; +Cc: pclouds

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v2 2/3] git-submodule.txt: make subcommands underlined
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
  2019-02-12  9:56   ` [PATCH v2 1/3] git-remote.txt: be specific about " Denton Liu
@ 2019-02-12  9:56   ` Denton Liu
  2019-02-13  8:15     ` Denton Liu
  2019-02-12  9:56   ` [PATCH v2 3/3] submodule: document default behavior Denton Liu
  2019-02-15  9:26   ` [PATCH v3 0/1] Document git-submodule's " Denton Liu
  3 siblings, 1 reply; 14+ messages in thread
From: Denton Liu @ 2019-02-12  9:56 UTC (permalink / raw)
  To: git; +Cc: pclouds

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v2 3/3] submodule: document default behavior
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
  2019-02-12  9:56   ` [PATCH v2 1/3] git-remote.txt: be specific about " Denton Liu
  2019-02-12  9:56   ` [PATCH v2 2/3] git-submodule.txt: make subcommands underlined Denton Liu
@ 2019-02-12  9:56   ` Denton Liu
  2019-02-13 18:39     ` Junio C Hamano
  2019-02-15  9:26   ` [PATCH v3 0/1] Document git-submodule's " Denton Liu
  3 siblings, 1 reply; 14+ messages in thread
From: Denton Liu @ 2019-02-12  9:56 UTC (permalink / raw)
  To: git; +Cc: pclouds

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined
  2019-02-12  9:56   ` [PATCH v2 2/3] git-submodule.txt: make subcommands underlined Denton Liu
@ 2019-02-13  8:15     ` Denton Liu
  2019-02-13  9:55       ` Duy Nguyen
  2019-02-13 18:30       ` Junio C Hamano
  0 siblings, 2 replies; 14+ messages in thread
From: Denton Liu @ 2019-02-13  8:15 UTC (permalink / raw)
  To: git; +Cc: pclouds

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

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined
  2019-02-13  8:15     ` Denton Liu
@ 2019-02-13  9:55       ` Duy Nguyen
  2019-02-13 18:30       ` Junio C Hamano
  1 sibling, 0 replies; 14+ messages in thread
From: Duy Nguyen @ 2019-02-13  9:55 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 2/3] git-submodule.txt: make subcommands underlined
  2019-02-13  8:15     ` Denton Liu
  2019-02-13  9:55       ` Duy Nguyen
@ 2019-02-13 18:30       ` Junio C Hamano
  1 sibling, 0 replies; 14+ messages in thread
From: Junio C Hamano @ 2019-02-13 18:30 UTC (permalink / raw)
  To: Denton Liu; +Cc: git, pclouds

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.


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 3/3] submodule: document default behavior
  2019-02-12  9:56   ` [PATCH v2 3/3] submodule: document default behavior Denton Liu
@ 2019-02-13 18:39     ` Junio C Hamano
  2019-02-14  7:24       ` Denton Liu
  0 siblings, 1 reply; 14+ messages in thread
From: Junio C Hamano @ 2019-02-13 18:39 UTC (permalink / raw)
  To: Denton Liu; +Cc: git, pclouds

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

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 3/3] submodule: document default behavior
  2019-02-13 18:39     ` Junio C Hamano
@ 2019-02-14  7:24       ` Denton Liu
  2019-02-14 17:41         ` Junio C Hamano
  0 siblings, 1 reply; 14+ messages in thread
From: Denton Liu @ 2019-02-14  7:24 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git, pclouds

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

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH v2 3/3] submodule: document default behavior
  2019-02-14  7:24       ` Denton Liu
@ 2019-02-14 17:41         ` Junio C Hamano
  0 siblings, 0 replies; 14+ messages in thread
From: Junio C Hamano @ 2019-02-14 17:41 UTC (permalink / raw)
  To: Denton Liu; +Cc: git, pclouds

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.

^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v3 0/1]  Document git-submodule's default behavior
  2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
                     ` (2 preceding siblings ...)
  2019-02-12  9:56   ` [PATCH v2 3/3] submodule: document default behavior Denton Liu
@ 2019-02-15  9:26   ` " Denton Liu
  2019-02-15  9:26     ` [PATCH v3 1/1] submodule: document " Denton Liu
  3 siblings, 1 reply; 14+ messages in thread
From: Denton Liu @ 2019-02-15  9:26 UTC (permalink / raw)
  To: git; +Cc: pclouds, gitster

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH v3 1/1] submodule: document default behavior
  2019-02-15  9:26   ` [PATCH v3 0/1] Document git-submodule's " Denton Liu
@ 2019-02-15  9:26     ` " Denton Liu
  0 siblings, 0 replies; 14+ messages in thread
From: Denton Liu @ 2019-02-15  9:26 UTC (permalink / raw)
  To: git; +Cc: pclouds, gitster

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


^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, back to index

Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-02-12  4:03 [PATCH] git-submodule.txt: document default behavior Denton Liu
2019-02-12  5:33 ` Duy Nguyen
2019-02-12  9:56 ` [PATCH v2 0/3] Document git-submodule's " Denton Liu
2019-02-12  9:56   ` [PATCH v2 1/3] git-remote.txt: be specific about " Denton Liu
2019-02-12  9:56   ` [PATCH v2 2/3] git-submodule.txt: make subcommands underlined Denton Liu
2019-02-13  8:15     ` Denton Liu
2019-02-13  9:55       ` Duy Nguyen
2019-02-13 18:30       ` Junio C Hamano
2019-02-12  9:56   ` [PATCH v2 3/3] submodule: document default behavior Denton Liu
2019-02-13 18:39     ` Junio C Hamano
2019-02-14  7:24       ` Denton Liu
2019-02-14 17:41         ` Junio C Hamano
2019-02-15  9:26   ` [PATCH v3 0/1] Document git-submodule's " Denton Liu
2019-02-15  9:26     ` [PATCH v3 1/1] submodule: document " Denton Liu

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox