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

[David Aguilar <davvid@gmail.com>]

On Sat, Dec 4, 2021 at 1:04 AM Fernando Ramos <greenfoo@u92.eu> wrote:
>
> 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.


> 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