Re: [PATCH 5/6] line-log: mention both modes in 'blame' and 'log' short help

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 28, 2020, 17:33 UTC
Message-ID: <CAPig+cRFaT9ww3K368b58m-xgW843jhZWjXDspVrfdyYY-_wRA@mail.gmail.com>
In-Reply-To: <27ef94e9cc4189c3d74e984437dcce24e1f29678.1603889270.git.gitgitgadget@gmail.com>

On Wed, Oct 28, 2020 at 8:48 AM Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 15 quoted lines

> 'git blame -h' and 'git log -h' both show '-L <n,m>' and describe this
> option as "Process only line range n,m, counting from 1". No hint is
> given that a function name regex can also be used.
>
> Use <range> instead, and expand the description of the option to mention
> both modes. Remove "counting from 1" as it's uneeded; it's uncommon to
> refer to the first line of a file as "line 0".
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
> diff --git a/builtin/blame.c b/builtin/blame.c
> @@ -889,7 +889,8 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
> -               OPT_STRING_LIST('L', NULL, &range_list, N_("n,m"), N_("Process only line range n,m, counting from 1")),
> +               OPT_STRING_LIST('L', NULL, &range_list, N_("range"),
> +                               N_("Process only the given line range (<range>=<start>,<end>) or function (<range>=:<funcname>)")),

The "<range>=" bit is redundant and confusing (and ugly). Considering that the description already says "Process only the given line _range_", it should be fine to drop the "<range>=" lead-in. Perhaps:

    Process only the given line range <start>,<end> or :<funcname>"

This might feel too succinct, but that's often true of short -h help. Such succinctness is generally acceptable as long as more detailed documentation can be discovered easily (such as in the 'man' page).

Same comment regarding the rest of the changes in this patch.