TortoiseGit & git integration

TortoiseGit

TortoiseGit starts one DiffScope window per file and waits for it to close. Both settings live on the Diff Viewer page of the TortoiseGit settings.

Diff viewer

1. Right-click in Explorer › TortoiseGit › Settings.
2. Select Diff Viewer in the tree on the left.
3. Under Configure the program used for comparing different revisions of files, choose External.
4. Paste this command line into the box, change the path, and click Apply:

"C:\Tools\DiffScope\DiffScope.exe" %base %mine /title1=%bname /title2=%yname /leftreadonly

%base is the older version on the left and %mine the newer one on the right. /leftreadonly protects the left side, which is usually a temporary copy of an old revision. When the right side is your working-tree file, you can edit it and save with Ctrl+S.

Merge tool

1. In the same settings dialog, expand Diff Viewer and select Merge Tool.
2. Choose External.
3. Paste this command line, change the path, and click OK:

"C:\Tools\DiffScope\DiffScope.exe" /base:%base /mine:%mine /theirs:%theirs /merged:%merged /basename:%bname /minename:%yname /theirsname:%tname /mergedname:%mname

On a conflict, right-click the file › TortoiseGit › Edit conflicts. DiffScope opens the 3-way merge. Resolve the conflicts, save with Ctrl+S and close the window. Then mark the file resolved (right-click › TortoiseGit › Resolve…).

TortoiseGit placeholders

TortoiseGit puts double quotes around each value itself, so do not add quotes around the placeholders.

If a diff command contains no %base or %mine, TortoiseGit appends the two file names at the end. DiffScope treats that as an ordinary two-file compare.

Automatic setup (source builds only)

The DiffScope source repository includes scripts\integration\install-tortoisegit.ps1 and uninstall-tortoisegit.ps1. They write the same two settings, back up your previous tools and restore them on uninstall. These scripts are not in the 1.0.0 zip. If you use the zip, follow the manual steps above.

git difftool and mergetool

git runs tool commands through its own shell, so the git setup uses GNU-style options (--merge --base …) rather than /switch: forms, and forward slashes in the path.

Option 1: edit .gitconfig

Run git config --global --edit (or open %USERPROFILE%\.gitconfig) and add:

[diff]
    tool = diffscope
[merge]
    tool = diffscope
[difftool "diffscope"]
    cmd = \"C:/Tools/DiffScope/DiffScope.exe\" \"$LOCAL\" \"$REMOTE\" --left-readonly
[mergetool "diffscope"]
    cmd = \"C:/Tools/DiffScope/DiffScope.exe\" --merge --base \"$BASE\" --mine \"$LOCAL\" --theirs \"$REMOTE\" --output \"$MERGED\"
    trustExitCode = true

The \" sequences are needed: git turns them into plain quotes, so paths with spaces arrive intact.

Option 2: git config commands

The same settings from Git Bash:

EXE='C:/Tools/DiffScope/DiffScope.exe'
git config --global diff.tool diffscope
git config --global merge.tool diffscope
git config --global difftool.diffscope.cmd "\"$EXE\" \"\$LOCAL\" \"\$REMOTE\" --left-readonly"
git config --global mergetool.diffscope.cmd "\"$EXE\" --merge --base \"\$BASE\" --mine \"\$LOCAL\" --theirs \"\$REMOTE\" --output \"\$MERGED\""
git config --global mergetool.diffscope.trustExitCode true

Why trustExitCode matters

With trustExitCode = true, git marks a file resolved only when DiffScope exits with code 0, which happens when you saved the merge with no conflicts left. Code 1 (closed without saving, or saved with conflict markers) makes git report merge of <file> failed and keep the file conflicted. Without it, git only checks whether the file changed, and a file saved with conflict markers counts as changed. See exit codes.

Using it

# one window per changed file
git difftool
# compare a commit range as two folders in one window
git difftool --dir-diff HEAD~3
# one merge window per conflicted file
git mergetool

With --dir-diff (-d), git copies both sides into temporary folders and DiffScope opens a folder compare. Open individual files from there. git waits until every DiffScope window has closed. Add --no-prompt (-y) to skip git's "Launch 'diffscope'?" question.

Non-interactive merges

For scripts, add --headless to the merge command. DiffScope then merges without a window, writes conflict markers where needed and returns 0 or 1:

git -c mergetool.diffscope.cmd='"C:/Tools/DiffScope/DiffScope.exe" --headless --merge --base "$BASE" --mine "$LOCAL" --theirs "$REMOTE" -o "$MERGED"' \
    -c mergetool.diffscope.trustExitCode=true mergetool --tool=diffscope --no-prompt

Note that git difftool --trust-exit-code treats exit code 1 (files differ) as a failure.

Other tools

Any program that can run an external diff or merge tool can run DiffScope. Map the program's placeholders onto one of these forms:

Two-way tools that want left and right files (TortoiseSVN, TortoiseHg and similar) use the first form. Merge tools that expect "wait for exit, read the exit code" get 0 for a clean, saved merge and 1 otherwise. For the merge pane titles use /basename:, /minename:, /theirsname: and /mergedname:, or /title1:–/title4:. Every switch is listed in the command-line reference.

DiffScope 1.0.0 has been tested with TortoiseGit and git. If you set it up in another tool, check a diff and a merge before relying on it.

Troubleshooting

Paths with spaces

• Always quote the path to DiffScope.exe itself: "C:\Program Files\DiffScope\DiffScope.exe".
• In TortoiseGit, do not quote %base, %mine and the other placeholders. TortoiseGit already quotes them, and doubled quotes break the command line.
• In .gitconfig, write quotes as \" and use forward slashes: \"C:/Program Files/DiffScope/DiffScope.exe\".
• Do not end a quoted folder path with a backslash ("C:\dir\"). Windows reads \" as an escaped quote. Leave the trailing backslash off.

git says the merge failed, or marks it resolved too early

• merge of … failed after you closed the window means DiffScope exited with code 1: you closed without saving, or saved with conflicts left. Run git mergetool again to continue.
• If git marks files resolved that still contain conflict markers, trustExitCode is missing. Run git config --global mergetool.diffscope.trustExitCode true.
• A two-way diff window always exits with 0 when you close it, whether or not the files differ. Only headless mode returns 1 for "different".

The window opens and shows an error

DiffScope shows an error screen with the paths it received when a file is missing, a folder is paired with a file, or the command line cannot be parsed. Check the command against the examples above: the most common causes are a missing switch value (/base instead of /base:%base) or extra quotes around TortoiseGit placeholders.

SmartScreen blocks DiffScope

DiffScope.exe is not code-signed yet. Run it once by hand from Explorer and choose More info › Run anyway before you use it from TortoiseGit or git. If Windows marked the zip as downloaded from the internet, you can also right-click the zip › Properties › Unblock before extracting.

Removing the integration

• TortoiseGit: in Settings › Diff Viewer and Settings › Diff Viewer › Merge Tool, choose TortoiseGitMerge again (or your previous tool).
• git: remove the settings:

git config --global --unset diff.tool
git config --global --unset merge.tool
git config --global --remove-section difftool.diffscope
git config --global --remove-section mergetool.diffscope