From: Junio C Hamano <gitster@pobox.com>
To: Denton Liu <liu.denton@gmail.com>
Cc: git@vger.kernel.org, pclouds@gmail.com
Subject: Re: [PATCH v2 3/3] submodule: document default behavior
Date: Wed, 13 Feb 2019 10:39:48 -0800 [thread overview]
Message-ID: <xmqqzhqzbki3.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <d8785cdd01503f2a7b9a6fbc19105c41a9a04046.1549965172.git.liu.denton@gmail.com> (Denton Liu's message of "Tue, 12 Feb 2019 01:56:13 -0800")
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>...)
next prev parent reply other threads:[~2019-02-13 18:56 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqzhqzbki3.fsf@gitster-ct.c.googlers.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=liu.denton@gmail.com \
--cc=pclouds@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).