Git environment variables documentation

Question

I would like to make some changes to git-difftool for better support with BeyondCompare. I notice this Perl program use lots of ENV variables such as:

• GIT_DIFF_TOOL
• GIT_DIFFTOOL_EXTCMD
• GIT_DIFFTOOL_DIRDIFF
• GIT_DIFFTOOL_PROMPT
• GIT_PAGER

Unfortunately I did not find any documentation of these variables. Google is not my friend today...

EDIT

As answered by VonC, the above variables are related to git-difftool--helper.sh. I am still confused with GIT_EXTERNAL_DIFF. Git will launch git-difftool--helper.sh which iterates each 7-arguments. What are these arguments, where is the documentation related to it?

Answer 1

Note (update Q1 2017 with Git 2.12): difftool is no longer a perl program, but C builtin tool within Git.

See commit 94d3997 (25 Jan 2017) by Jeff King (peff).
See commit 019678d, commit 03831ef (19 Jan 2017), and commit be8a90e (17 Jan 2017) by Johannes Schindelin (dscho).
^{(Merged by Junio C Hamano -- gitster -- in commit b7786bb, 31 Jan 2017)}

---

Original answer March 2015:

git-difftool.perl simply uses those environment variable to give the user the opportunity to override the config value you can see in "Git Diff with Beyond Compare".

Those environment variables are used in git-difftool--helper.sh, where they can override the local config.

diff config mentions the config diff.external which can be overriden by the GIT_EXTERNAL_DIFF environment variable.
That command is meant to be called with parameters as described under "git Diffs" of git.

That is where the 7 parameters are documented:

'GIT_EXTERNAL_DIFF'::

When the environment variable 'GIT_EXTERNAL_DIFF' is set, the program named by it is called, instead of the diff invocation described above. For a path that is added, removed, or modified,

'GIT_EXTERNAL_DIFF' is called with 7 parameters:

path old-file old-hex old-mode new-file new-hex new-mode

where:

• <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the contents of <old|new>,

• <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
• <old|new>-mode:: are the octal representation of the file modes.

---

With Git 2.29 (Q4 2020), the role of GIT_EXTERNAL_DIFF is clarified.

See commit 17bae89 (01 Sep 2020) by Philippe Blain (phil-blain).
^{(Merged by Junio C Hamano -- gitster -- in commit cd332b2, 03 Sep 2020)}

git.txt: correct stale 'GIT_EXTERNAL_DIFF' description

^{Signed-off-by: Philippe Blain}

In fde97d8ac6 ("Update documentation to remove incorrect GIT_DIFF_OPTS example.", 2006-11-27, Git v1.5.0-rc0 -- merge), the description of the 'GIT_EXTERNAL_DIFF' variable was moved from 'diff-format.txt' to 'git.txt', and the documentation was updated to remove a 'diff' invocation since Git did not use an external diff program anymore by default.

However, the description of 'GIT_EXTERNAL_DIFF' still mentions "instead of the diff invocation described above", which is confusing.

Correct that outdated sentence.

git now includes in its man page:

GIT_EXTERNAL_DIFF:

When the environment variable GIT_EXTERNAL_DIFF is set, the program named by it is called to generate diffs, and Git does not use its builtin diff machinery.

Answer 2

I use git and Beyond Compare and I never used any script to configure them.

An excerpt from the output of git config --global --list:

difftool.bcomp.cmd=/usr/local/bin/bcomp "$LOCAL" "$REMOTE" "$BASE" "$MERGED"
difftool.bcomp.trustexitcode=true
diff.tool=bcomp

You need to install the command line tools of Beyond Compare. This is very simple: just select the "Install Command Line Tools..." command from the menu of Beyond Compare and follow the instructions (it asks you for your password because it needs to operate in system directories).

When it finishes it displays:

Successfully installed command line tools.

/usr/local/bin/bcomp:
Launches comparison and waits for it to complete.

/usr/local/bin/bcompare:
Launches comparison and returns immediately.

Then you configure git using:

git config --global --add difftool.bcomp.cmd '/usr/local/bin/bcomp "$LOCAL" "$REMOTE" "$BASE" "$MERGED"'
git config --global --add difftool.bcomp.trustexitcode true
git config --global --add diff.tool bcomp

Check if everything is set up correctly:

git difftool file.txt

(replace file.txt with the name of a real file that was changed in your repository).

Additionally, if you run:

git config --global --add mergetool.prompt false

then git difftool will launch the selected diff program (bcomp in this case) without asking for confirmation (as it does by default).