[PATCH] documentation: git-mergetool updated to warn against builtin tools invocations

From: Sylvain Rabot <srabot@steek.com>
Date: Jun 2, 2010, 17:57 UTC
Message-ID: <1275501453-13081-1-git-send-email-srabot@steek.com>

For known tools such as meld, diffuse, p4merge, git-mergetool ignores the mergetool.<tool>.* configurations. It took me a while to understand why my mergetool.diffuse.cmd configuration was not taken care of.

This documentation update warns against this behavior and explains how to setup a customized command line invocation for known diff tools.

Signed-off-by: Sylvain Rabot <srabot@steek.com>
---
 Documentation/git-mergetool.txt |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 55735fa..ac41d7c 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -45,6 +45,21 @@ Instead of running one of the known merge tool programs,
 by specifying the command line to invoke in a configuration
 variable `mergetool.<tool>.cmd`.
 +
+Be aware that 'git mergetool' has some predefined invocation commands builtin
+for known diff tools like meld, diffuse, p4merge ... etc. It means that if
+you set the merge.tool configuration to one of these tools, the 
+mergetool.<tool>.* configurations will not be taken care of. If you
+really want to customize the invocation of one of these tools, 
+set `merge.tool` to "custom" or whatever you want and `mergetool.custom.cmd` 
+to "/usr/bin/<tool> $LOCAL $MERGED $REMOTE"
++
+-------------
+[merge]
+    tool = diffuse-custom
+[mergetool "diffuse-custom"]
+    cmd = diffuse $LOCAL $MERGED $REMOTE
+-------------
++
 When 'git mergetool' is invoked with this tool (either through the
 `-t` or `--tool` option or the `merge.tool` configuration
 variable) the configured command line will be invoked with `$BASE`

-- 
1.7.1