Re: [PATCH v4 2/3] vimdiff: add tool documentation

From: David Aguilar <davvid@gmail.com>
Date: Dec 10, 2021, 02:58 UTC
Message-ID: <CAJDDKr77YQKJj15V52Rs=LPRMZVSkbpV8MWFDWNuYf4jqqCajg@mail.gmail.com>
In-Reply-To: <20211204090351.42369-3-greenfoo@u92.eu>

On Sat, Dec 4, 2021 at 1:04 AM Fernando Ramos <greenfoo@u92.eu> wrote:

Show 24 quoted lines

>
> Running 'git {merge,diff}tool --tool-help' now also prints usage
> information about the vimdiff tool (and its variantes) instead of just
> its name.
>
> Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been
> added to the set of functions that each merge tool (ie. scripts found
> inside "mergetools/") can overwrite to provided tool specific
> information.
>
> Right now, only 'mergetools/vimdiff' implements these functions, but
> other tools are encouraged to do so in the future, specially if they
> take configuration options not explained anywhere else (as it is the
> case with the 'vimdiff' tool and the new 'layout' option)
>
> Signed-off-by: Fernando Ramos <greenfoo@u92.eu>
> ---
>  Documentation/git-difftool--vimdiff.txt  |  40 +++++
>  Documentation/git-mergetool--vimdiff.txt | 195 +++++++++++++++++++++++
>  git-mergetool--lib.sh                    |  14 ++
>  mergetools/vimdiff                       |  12 ++
>  4 files changed, 261 insertions(+)
>  create mode 100644 Documentation/git-difftool--vimdiff.txt
>  create mode 100644 Documentation/git-mergetool--vimdiff.txt

Should these be referenced from elsewhere in the Documentation/ tree in order to make them more discoverable?

Documentation/git-{difftool,mergetool}.txt seem like they should include or link to these.

Show 31 quoted lines

> diff --git a/mergetools/vimdiff b/mergetools/vimdiff
> index 5bf77a5388..db6cb75728 100644
> --- a/mergetools/vimdiff
> +++ b/mergetools/vimdiff
> @@ -364,6 +364,12 @@ diff_cmd () {
>  }
>
>
> +diff_cmd_help() {
> +       echo "Run 'man git-difftool--vimdiff' for details"
> +       return 0
> +}
> +
> +
>  merge_cmd () {
>         layout=$(git config mergetool.$merge_tool.layout)
>
> @@ -435,6 +441,12 @@ merge_cmd () {
>  }
>
>
> +merge_cmd_help() {
> +       echo "Run 'man git-mergetool--vimdiff' for details"
> +       return 0
> +}
> +
> +
>  translate_merge_tool_path() {
>         case "$1" in
>         nvimdiff*)
> --

My understanding is that we prefer "git help" instead of "man" when providing hints.

That means we should suggest something like this instead:

        echo "Run 'git help mergetool--vimdiff' for details"

-- David