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

On Mon, Jul 23, 2012 at 1:14 PM, Sebastian Schuberth
[off-list ref] wrote:

On Mon, Jul 23, 2012 at 9:52 PM, Junio C Hamano [off-list ref] wrote:

quoted

quoted

 -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.

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