Sublimerge Pro (2.x) documentation

VCS integration

Besides built-in support for the most popular Version Control Systems, Sublimerge can be also integrated with them as a diff and merge tool. Because it can be run from command line, you can integrate it with anything. Please be aware of possible integration issues.

Command templates

All examples here assumes that Sublime Text binary is in your PATH. Here `subl` is used to refer to Sublime Text executable, but remember that under Windows this will be `sublime_text.exe`.

Prepare environment (OS X)

Sublime Text requires a little setup under Mac OS X.

Assuming you've installed Sublime Text in Applications and you have a ~/bin directory in your PATH, please do the following to create a symlink to Sublime's binary:

Sublime Text 2
ln -s "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl" ~/bin/subl
Sublime Text 3
ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" ~/bin/subl

This way you get subl command that this document refers to.

Diff tool (2-way)

subl -n --wait "<LEFT>" "<RIGHT>" --command "sublimerge_diff_views {\"left_read_only\": true, \"right_read_only\": true}"

Merge tool (3-way)

subl -n --wait "<THEIRS>" "<BASE>" "<MINE>" "<MERGED>" --command "sublimerge_diff_views"

Available parameters

left_read_only true/false
When true, opens left file in read only mode. For 2-way diff defaults to false. For 3-way diff is always forced to true.
right_read_only true/false
When true, opens left right in read only mode. For 2-way diff defaults to false. For 3-way diff is always forced to true.
full_screen false
Whether to open diff view in full screen mode. Possible values: true, false, null. When set to null, defaults to full_screen value from Sublimerge config.

TortoiseGit/TortoiseSVN

Diff tool

TortoiseGit - Diff Viewer
sublime_text.exe -n --wait %base %mine --command "sublimerge_diff_views {\"left_read_only\": true, \"right_read_only\": true}"

Merge tool

TortoiseGit - Merge Tool
sublime_text.exe -n --wait %theirs %base %mine %merged --command "sublimerge_diff_views"

Git

~/.gitconfig
[merge]
tool = sublimerge

[mergetool "sublimerge"]
cmd = subl -n --wait \"$REMOTE\" \"$BASE\" \"$LOCAL\" \"$MERGED\" --command \"sublimerge_diff_views\"
trustExitCode = false

[diff]
tool = sublimerge

[difftool "sublimerge"]
cmd = subl -n --wait \"$REMOTE\" \"$LOCAL\" --command \"sublimerge_diff_views {\\\"left_read_only\\\": true, \\\"right_read_only\\\": true}\"

Mercurial (Hg)

~/.hgrc
[extensions]
hgext.extdiff =

[extdiff]
cmd.sublimerge = subl

[merge-tools]
sublimerge.executable = subl
sublimerge.args = -n --wait $other $base $local $output --command \"sublimerge_diff_views\"
sublimerge.diffargs = -n --wait $parent $child --command \"sublimerge_diff_views {\\\"left_read_only\\\": true, \\\"right_read_only\\\": true}\"
sublimerge.gui = True
sublimerge.check = changed

Subversion (SVN)

SVN configuration is a little bit complicated. It requires creating two bash scripts (Windows users will need to create similar BAT files) for svn diff --diff-cmd and svn diff --diff3-cmd commands.

2-way diff script

#!/bin/bash
subl -n --wait ${6} ${7} --command "sublimerge_diff_views {\"left_read_only\": true, \"right_read_only\": true}"

# Always return 0. There is no way to pass exit code from Sublimerge.
exit 0

To run Sublimerge on modified files, run the following command:


svn diff --diff-cmd <path to above script> <file name>

3-way diff script

#!/bin/bash
MINE=${9}
BASE=${10}
THEIR=${11}
OUTPUT=${MINE}.sublimerge-tmp

subl -n --wait $THEIR $BASE $MINE $OUTPUT --command "sublimerge_diff_views"

# Yes, this is required. SVN writes stdout content to a merged file.
cat $OUTPUT
rm $OUTPUT

# Always return 0. There is no way to pass exit code from Sublimerge.
exit 0

To resolve conflicts during update, run the following command:


svn update --diff3-cmd <path to above script> <file name>

To make it default for svn diff command, put the following contents into ~/.subversion/config:


[helpers]
diff-cmd = <path to 2-way script>
merge-tool-cmd = <path to 3-way script>

Possible integration issues

ST2/ST3: running Sublimerge from command line restores last Sublime's session (only when ST was not already running).
Probably there is no good way to fix this since this is "normal" Sublime's behavior. See this discussion for more information and possible solution.
ST3: running Sublimerge from command line (only when Sublime Text was not already running) only opens files without doing diff. Otherwise, when launching Sublimerge while ST is running, everything works fine.
This is caused by asynchronous plugins loader in ST3 and cannot be fixed from plugin level.
OS X: When MacPorts version of Python is installed, running Sublimerge fails when there is no Sublime Text instance running.
According to information on this page, please open Sublime Text first and then run Sublimerge via subl command.
I serve cookies to improve your experience on this website. If you continue without changing your browser settings, I will assume that you accept the cookies. You can change your browser settings at any time.