Re: [PATCH] mergetool: support --tool-help option like difftool does

From: David Aguilar <davvid@gmail.com>
Date: Jul 23, 2012, 20:44 UTC
Message-ID: <CAJDDKr4TyDp5vxqqHGkBBSiMJXJHW528+nqrag9Rgz+vksqjhg@mail.gmail.com>
In-Reply-To: <CAHGBnuMCsxmVN8fCSgazqKUwtJzJJxtrVxjKwCEEhZJ_U0cW9w@mail.gmail.com>

On Mon, Jul 23, 2012 at 1:14 PM, Sebastian Schuberth <sschuberth@gmail.com> wrote:

Show 19 quoted lines

> On Mon, Jul 23, 2012 at 9:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
>>>  -t <tool>::
>>>  --tool=<tool>::
>>> -     Use the diff tool specified by <tool>.  Valid values include
>>> -     emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`
>>> -     for the list of valid <tool> settings.
>>> +     Use the diff tool specified by <tool>.
>>
>> I do not see how it is an improvement to drop the most common ones.
>> People sometimes read documentation without having an access to
>> shell to run "cmd --tool-help", and a list of handful of well known
>> ones would serve as a good hint to let the reader know the kind of
>> commands the front-end is capable of spawning, which in turn help
>> such a reader to imagine how the command is used to judge if it is
>> something the reader wants to use.
>
> I don't agree. What "most common ones" are depends on your platform
> and is sort of subjective. So it should be either all or non here.

Let's please leave this section as-is.

This part of the documentation has had a fair amount of churn. Specifically, it would get touched every time a new tool was added.

The point of bf73fc212a159210398b6d46ed5e9101c650e7db was to change it *one last time* into something that is helpful, but not a substitute for the real list output by --tool-help.

If any changes are done then it should be to make git-mergetool.txt match the advice given in git-difftool.txt.

Show 6 quoted lines

> Your argument about people not having shell access is a valid one, but
> still that would mean to list all tools in my opinion. And listing all
> tools again thwarts our goal to reduce the number of places where new
> merge / diff tools need to be added. For people adding new merge /
> diff tools it is just clearer what places need to be modified if there
> are no places that list an arbitrary subset of tools.

Yes, indeed, it is arbitrary. It does have some merit, though--it is also a good compromise between unhelpful (listing nothing) and painful to maintain (listing everything).

-- 
David