Command line (dp)

DiffPlug can be automatated using the dp command line tool. The dp included in DiffPlug 2 is not backward-compatible with DiffPlug 1.

Installation

Windows

dp.bat lives in the DiffPlug installation directory. All you have to do is add this directory to your system path.

Open system

Set the path variable

If it's not working as expected:

  • open new cmd prompt
  • run where dp
  • it should print the directory you just added
  • if it doesn't, there is another folder earlier in the path with dp

Mac

The dp executable lives in the DiffPlug.app/Contents/Resources/dp. To make it easily available everywhere, just run

sudo ln -s /Applications/DiffPlug.app/Contents/Resources/dp /usr/local/bin/dp

If it's not working as expected:

  • open a new terminal
  • run which dp
  • it should print /usr/local/bin/dp
  • then ls -l /usr/local/bin/dp
  • it should print /Applications/DiffPlug.app/Contents/Resources/dp

It is fine to put DiffPlug.app somewhere else besides /Applications, just change the instructions appropriately.

Linux

The dp executable lives in the <DiffPlug install directory>/dp. To make it easily available everywhere, just run

sudo ln -s <DiffPlug install directory>/dp /usr/local/bin/dp

If it's not working as expected:

  • open a new terminal
  • run which dp
  • it should print /usr/local/bin/dp
  • then ls -l /usr/local/bin/dp
  • it should print <DiffPlug install directory>/dp

General usage

dp will connect to whichever instance of DiffPlug 2 was launched most recently.

To see what commands are available, simply run dp at a console.

cmd> dp
You must specify a command.

usage: dp <command> [args ...]

'dp help <command>' for more info.  Available commands:
add           Adds the given paths to the palette
cat           Dumps an entity's binary content to standard output
slurp         Slurps standard input into the given entity
ext           Integration with external vcs clients (open, diff, and merge)

To get help for a particular command, type dp help <command>

cmd> dp help ext
Integration with external vcs clients (open, diff, and merge)

usage: dp ext -before FILE [-after FILE] [-ours FILE] [-theirs FILE] [-result FILE]
-before FILE : base file
-after FILE  : 2-way diff - file after change
-ours FILE   : 3-way diff - file after our changes
-theirs FILE : 3-way diff - file after their changes
-result FILE : editiable version of file, converts diff to merge

<Further docs>

dpopen helper script

dp is a general-purpose interface to DiffPlug - it's not just about opening files. However, "just open this file" is a common usecase, and sometimes you are not able to configure the arguments and flags necessary for dp to open a file. For this purpose, there is the dpopen helper script. It is actually an alias to dp ext -before <FILENAME>, and it allows you to integrate DiffPlug with tools that don't accept configurable arguments.

Integrating with external tools using "dp ext"

One of dp ext's features is that the dp will remain running so long as the files it referenced are still open in DiffPlug. You can have multiple calls to dp ext, and each will close at the appropriate time when you have stopped using those temporary files in DiffPlug.

This is especially important for comparing folders, and using DiffPlug as a conflict resolution tool.

Here are some quick integrations for common version control tools:

git

You can make command line git and CLI-based gui clients such as "Git Extensions" work with DiffPlug by setting your ~/.gitconfig to match the following:

FOR WINDOWS USERS: you must use forward-slashes, and if your path contains any spaces you must use single-quotes to encapsulate the path, as shown below

FOR MAC/LINUX USERS: you should remove the .bat from dp.bat

[difftool "diffplug"]
	cmd = 'C:/path to DiffPlug/dp.bat' ext -flavor git -before "$LOCAL" -beforeName "before:/$MERGED" -after "$REMOTE" -afterName "after:/$MERGED" -result "$MERGED"
[mergetool "diffplug"]
	cmd = 'C:/path to DiffPlug/dp.bat' ext -flavor git -before "$BASE" -beforeName "before:/$MERGED" -ours "$LOCAL" -oursName "ours:/$MERGED" -theirs "$REMOTE" -theirsName "theirs:/$MERGED" -result "$MERGED"
[merge]
	tool = diffplug
	guitool = diffplug
[diff]
	tool = diffplug
	guitool = diffplug

Further reading: git difftool, git mergetool.

Git Extensions

DO NOT USE THE SETTINGS GUI, just use a regular text editor with the instructions for git above. The Git Extensions settings gui will add escape characters which may cause problems.

Atlassian SourceTree

  • From the menu bar, select Tools -> Options
    • SourceTree tools options
  • In the Diff tab, set External Diff / Merge to:
    • Diff Arguments: ext -flavor git -before "$LOCAL" -beforeName "before:/$MERGED" -after "$REMOTE" -afterName "after:/$MERGED" -result "$MERGED"
    • Merge Arguments: ext -flavor git -before "$BASE" -beforeName "before:/$MERGED" -ours "$LOCAL" -oursName "ours:/$MERGED" -theirs "$REMOTE" -theirsName "theirs:/$MERGED" -result "$MERGED"
    • SourceTree tools options
  • Now, whenever you click a changed file, you can click the gear drop down and select External Diff to open the diff in DiffPlug.
    • SourceTree tools options
  • NOTE: SourceTree will only allow one "External Diff" to happen at a time. You have to close the previous diff in DiffPlug before SourceTree will initiate a new diff.

TortoiseGit

  • From windows explorer, right-click a repository, then select TortoiseGit -> Settings (it will be towards the bottom).
  • Select Diff Viewer in the left side pane
    • For "Configure the program used for comparing different revisions of files", select External then enter:
      • <path to dp> ext -flavor tortoiseGitDiff -before %base -beforeName %bname -after %mine -afterName %yname -result %ypath
    • Leave "Configure viewer program for GNU diff files (patch files)" alone
    • TortoiseGit diff
  • Select Merge Tool in the left side pane
    • Enter the line: <path to dp> ext -flavor tortoiseGitMerge -before %base -beforeName %bname -ours %mine -oursName %yname -theirs %theirs -theirsName %tname -result %merged
    • TortoiseGit merge

mercurial and TortoiseHg

Set your ~/mercurial.ini to be similar to the following:

[tortoisehg]
vdiff=diffplug2

[merge-tools]
diffplug2.executable = PATH_TO_EXTRACTED_FOLDER\dp.bat
diffplug2.args = ext -flavor tortoiseHg -before $base -ours $local -theirs $other -result $output
diffplug2.diffargs= ext -flavor tortoiseHg -before $parent -after $child -beforeName '$plabel1' -afterName '$clabel'
diffplug2.diff3args= ext -flavor tortoiseHg -before $parent1 -beforeName '$plabel1' -ours $child -oursName '$clabel' -theirs $parent2 -theirsName '$plabel2'
diffplug2.binary = true
diffplug2.symlink = false
diffplug2.gui = true
diffplug2.priority = 1
diffplug2.dirdiff=True

[merge-patterns]
**.slx = diffplug2
**.mdl = diffplug2

[ui]
diff = diffplug2
merge = diffplug2

Further reading: hg merge tool.

TortoiseSVN

  • From windows explorer, right-click a repository, then select TortoiseSVN -> Settings (it will be towards the bottom).
  • Select Diff Viewer in the left side pane
    • For "Configure the program used for comparing different revisions of files" select External and then enter:
    • C:\PathTo\dp.bat ext -flavor tortoiseSVN -before %base -beforeName %bname -after %mine -afterName %yname
    • TortoiseSVN diff
  • Select Merge Tool in the left side pane
    • For "Configure the program used to resolve conflicted files" select External and then enter:
    • C:\PathTo\dp.bat ext -flavor tortoiseSVN -before %base -beforeName %bname -ours %mine -oursName %yname -theirs %theirs -theirsName %tname -result %merged
    • TortoiseSVN merge

Perforce (Helix Client P4V)

  • From the menu bar, select Edit -> Preferences.
  • Select File Editors in the left side pane
    • For any files you want to use DiffPlug to open, select Add...
    • For Application, enter the path to dpopen, not dp, and be sure to check Always use the selected application to open files of this type
    • Perforce P4V File Editors
  • Select Diff in the left side pane
    • To use DiffPlug for all diffs, select Other application, or to use DiffPlug for only a specific filetype such as .mdl or .slx, click Add...
    • Arguments: ext -before %1 -after %2
    • Perforce P4V File Editors
  • Select Merge in the left side pane
    • To use DiffPlug for all merges, select Other application, or to use DiffPlug for only a specific filetype such as .mdl or .slx, click Add...
    • Arguments: ext -before %b -theirs %1 -ours %2 -result %r
    • Perforce P4V File Editors

Debugging

When an external program calls dp, it can be hard to ensure that the arguments are being passed correctly. For that purpose you can use the command console to open the Log all calls to dp tool.

How to open the 'log all calls to dp' window

This will open a window which makes it easy to see exactly what was passed to DiffPlug, and what DiffPlug passed back.

How to open the 'log all calls to dp' window