On Mon, Jul 23, 2012 at 1:14 PM, Sebastian Schuberth <sschuberth@xxxxxxxxx> wrote: > On Mon, Jul 23, 2012 at 9:52 PM, Junio C Hamano <gitster@xxxxxxxxx> 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. > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html