On 21/12/11 11:46AM, Fernando Ramos wrote:
> On 21/12/09 06:58PM, David Aguilar wrote:
> > On Sat, Dec 4, 2021 at 1:04 AM Fernando Ramos <greenfoo@xxxxxx> 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.
> > >
> > > Signed-off-by: Fernando Ramos <greenfoo@xxxxxx>
> > > ---
> > > Documentation/git-difftool--vimdiff.txt | 40 +++++
> > > Documentation/git-mergetool--vimdiff.txt | 195 +++++++++++++++++++++++
> >
> >
> > 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.
>
> Those files (Documentation/git-{difftool,mergetool}.txt) contain this piece of
> text:
>
> --tool-help
> Print a list of diff tools that may be used with --tool.
>
> When you then run with "--tool-help", not only the list of available tools is
> listed, but also a short message explaining how to obtain more details is
> presented (for those tools that have more information):
>
> vimdiff
> Run 'man git-difftool--vimdiff' for details
>
> In other words: there is one level of "indirection" that decouples the
> documentation of each tool from the generic documentation contained in
> Documentation/git-{difftool,mergetool}.txt.
>
> Thanks to this, when documentation for a new tool is created in the future, as
> long as the "diff_cmd_help()/merge_cmd_help()" functions are overwritten,
> everything will "just work" without having to edit
> Documentation/git-{difftool,mergetool}.txt each time.
>
> I thought this was the best option but I have not problem adding a reference to
> it if you prefer that (maybe at the end, in the "SEE ALSO" section?)
>
> Let me know what you think.
>
>
> > > +merge_cmd_help() {
> > > + echo "Run 'man git-mergetool--vimdiff' for details"
> > > + return 0
> > > +}
> > > +
> > > +
> >
> > 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"
>
> I originally typed that, but then I noticed something in my system: all entries
> in "Documentation/" seem to be available as "man" pages, but only a subset of
> them are also available through "git help". Examples:
>
> * man git-mergetool --> works
> * man git-mergetool--lib --> works
>
> * git help mergetool --> works
> * git help mergetool--lib --> does not work!
>
> That's why I ended up using "man".
>
> PS: Now that I have revisited the issue, it looks like the command that is
> failing is trying to run "man gitmergetool--lib" under the hood (notice there is
> a missing "-"). The problem seems to be in "builtin/help.c:cmd_to_page()":
>
> if is_git_command(x)
> return xstrfmt("git-%s", x);
> else
> return xstrfmt("git%s", x);
>
> Because "mergetool--lib" is not a regular git command, it removes the "-". The
> same would happen to the new "git help mergetool--vimdiff" if I add it. Is
> this the intended behavior?
>
> There are two options:
>
> A) This is actually an error in help.c logic that needs to be fixed and then
> I can update the docs to "git help mergetool--vimdiff".
>
> B) This is the intended behavior and I leave "man git-mergetool--vimdiff" in
> the docs.
>
> I would say the right option is (A), but need your input regarding how to fix
> it.
>
> Thanks.
>
Any extra thoughts on these considerations?
Thanks!
