git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Junio C Hamano <gitster@pobox.com>
Date
Jul 23, 2012, 21:16 UTC
Message-ID
<7vmx2qji03.fsf@alter.siamese.dyndns.org>
In-Reply-To
<CAJDDKr4TyDp5vxqqHGkBBSiMJXJHW528+nqrag9Rgz+vksqjhg@mail.gmail.com>
David Aguilar <davvid@gmail.com> writes:
Show 23 quoted lines
> On Mon, Jul 23, 2012 at 1:14 PM, Sebastian Schuberth
> <sschuberth@gmail.com> wrote:
>> 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.
Yes.

There are only five or six classes of environment that matter in the real world for the purpose of giving "well known" examples: Windows, MacOS X, Gnome, KDE and Linux terminal. By picking a representative one from each and listing them, the end result would have at least one that people from various platforms have _heard of_ and can guess what they do. The "most common" is secondary, and "well known" is the keyword. "Can guess what they do" is the point of the phrase "Valid values _include_". Even if you are hard-core Emacs user, it is likely that you've heard of vimdiff---and in that case, including vimdiff would be enough. Likewise for showing kompare to Gnome users.

Unlike POSIXy folks, where IRIX or Solaris users are likely to have heard of Gnome tools even if they do not use the environment on their platforms, Windows users tend to be isolated bunch, so it would not hurt to include at least one well-known Windows-only tool in the list.

> 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).
Here is a v2, with documentation updates.
-- >8 --
Subject: [PATCH] mergetool: support --tool-help option like difftool does

This way we do not have to risk the list of tools going out of sync between the implementation and the documentation.

In the same spirit as bf73fc2 (difftool: print list of valid tools with '--tool-help', 2012-03-29), trim the list of merge backends in the documentation. We do not want to have a complete of valid tools there; we only want a list to help people guess what kind of things the tools that can be specified there, and refer them to --tool-help for a complete list.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-mergetool.txt |  6 +++---
 git-mergetool--lib.sh           |  6 +++++-
 git-mergetool.sh                | 42 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 49 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 2a49de7..d1e08d2 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -27,9 +27,9 @@ OPTIONS
 -t <tool>::
 --tool=<tool>::
 	Use the merge resolution program specified by <tool>.
-	Valid merge tools are:
-	araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3,
-	meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff.
+	Valid values include emerge, gvimdiff, kdiff3,
+	meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help`
+	for the list of valid <tool> settings.
 +
 If a merge resolution program is not specified, 'git mergetool'
 will use the configuration variable `merge.tool`.  If the
diff --git a/git-mergetool--lib.sh b/git-mergetool--lib.sh
index ed630b2..f730253 100644
--- a/git-mergetool--lib.sh
+++ b/git-mergetool--lib.sh
@@ -111,7 +111,7 @@ run_merge_tool () {
 	return $status
 }
 
-guess_merge_tool () {
+list_merge_tool_candidates () {
 	if merge_mode
 	then
 		tools="tortoisemerge"
@@ -136,6 +136,10 @@ guess_merge_tool () {
 		tools="$tools emerge vimdiff"
 		;;
 	esac
+}
+
+guess_merge_tool () {
+	list_merge_tool_candidates
 	echo >&2 "merge tool candidates: $tools"
 
 	# Loop over each candidate and stop when a valid merge tool is found.
diff --git a/git-mergetool.sh b/git-mergetool.sh
index a9f23f7..0db0c44 100755
--- a/git-mergetool.sh
+++ b/git-mergetool.sh
@@ -8,7 +8,7 @@
 # at the discretion of Junio C Hamano.
 #
 
-USAGE='[--tool=tool] [-y|--no-prompt|--prompt] [file to merge] ...'
+USAGE='[--tool=tool] [--tool-help] [-y|--no-prompt|--prompt] [file to merge] ...'
 SUBDIRECTORY_OK=Yes
 OPTIONS_SPEC=
 TOOL_MODE=merge
@@ -284,11 +284,51 @@ merge_file () {
     return 0
 }
 
+show_tool_help () {
+	TOOL_MODE=merge
+	list_merge_tool_candidates
+	unavailable= available= LF='
+'
+	for i in $tools
+	do
+		merge_tool_path=$(translate_merge_tool_path "$i")
+		if type "$merge_tool_path" >/dev/null 2>&1
+		then
+			available="$available$i$LF"
+		else
+			unavailable="$unavailable$i$LF"
+		fi
+	done
+	if test -n "$available"
+	then
+		echo "'git mergetool --tool=<tool>' may be set to one of the following:"
+		echo "$available" | sort | sed -e 's/^/	/'
+	else
+		echo "No suitable tool for 'git mergetool --tool=<tool>' found."
+	fi
+	if test -n "$unavailable"
+	then
+		echo
+		echo 'The following tools are valid, but not currently available:'
+		echo "$unavailable" | sort | sed -e 's/^/	/'
+	fi
+	if test -n "$unavailable$available"
+	then
+		echo
+		echo "Some of the tools listed above only work in a windowed"
+		echo "environment. If run in a terminal-only session, they will fail."
+	fi
+	exit 0
+}
+
 prompt=$(git config --bool mergetool.prompt || echo true)
 
 while test $# != 0
 do
     case "$1" in
+	--tool-help)
+		show_tool_help
+		;;
 	-t|--tool*)
 	    case "$#,$1" in
 		*,*=*)

-- 
1.7.11.3.339.gbdbf398
Previous: David AguilarNext: Sebastian Schuberth
Message 18 of 40 in “Various merge / diff tool related minor clean-ups and improvements”
  1. 0/4 Various merge / diff tool related minor clean-ups and improvementsSebastian Schuberth, Jul 23, 2012
  2. 0/5 Various merge / diff tool related minor clean-ups and improvementsSebastian Schuberth, Jul 23, 2012
  3. 1/5 Sort the list of tools that support both merging and diffing alphabeticallySebastian Schuberth, Jul 23, 2012
  4. 2/5 Use variables for the lists of tools that support merging / diffingSebastian Schuberth, Jul 23, 2012
  5. Junio C HamanoJul 23, 2012
  6. Sebastian SchuberthJul 23, 2012
  7. 1/4 Use variables for the lists of tools that support merging / diffingSebastian Schuberth, Jul 23, 2012
  8. Junio C HamanoJul 23, 2012
  9. Sebastian SchuberthJul 23, 2012
  10. 3/5 Explicitly list all valid diff tools and document --tool-help as an optionSebastian Schuberth, Jul 23, 2012
  11. Junio C HamanoJul 23, 2012
  12. mergetool: support --tool-help option like difftool doesJunio C Hamano, Jul 23, 2012
  13. Sebastian SchuberthJul 23, 2012
  14. mergetool: support --tool-help option like difftool doesSebastian Schuberth, Jul 23, 2012
  15. Junio C HamanoJul 23, 2012
  16. Sebastian SchuberthJul 23, 2012
  17. David AguilarJul 23, 2012
  18. Junio C HamanoJul 23, 2012
  19. Sebastian SchuberthJul 23, 2012
  20. Junio C HamanoJul 23, 2012
  21. Re*: mergetool: support --tool-help option like difftool doesJunio C Hamano, Aug 23, 2012
  22. David AguilarAug 23, 2012
  23. Junio C HamanoAug 23, 2012
  24. David AguilarAug 24, 2012
  25. Jens LehmannAug 26, 2012
  26. 4/5 Make sure to use Araxis' "compare" and not e.g. ImageMagick'sSebastian Schuberth, Jul 23, 2012
  27. Junio C HamanoJul 23, 2012
  28. Make sure to use Araxis' "compare" and not e.g. ImageMagick'sSebastian Schuberth, Jul 23, 2012
  29. Junio C HamanoJul 23, 2012
  30. Sebastian SchuberthJul 23, 2012
  31. Junio C HamanoJul 23, 2012
  32. Sebastian SchuberthJul 23, 2012
  33. David AguilarJul 23, 2012
  34. Sebastian SchuberthJul 23, 2012
  35. Andreas SchwabJul 23, 2012
  36. Junio C HamanoJul 23, 2012
  37. Sebastian SchuberthJul 23, 2012
  38. Junio C HamanoJul 23, 2012
  39. Sebastian SchuberthJul 23, 2012
  40. 5/5 Add a few more code comments and blank lines in guess_merge_toolSebastian Schuberth, Jul 23, 2012

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.