Skip to content

▶ Riffle

Riffle

Integrations

Riffle is built to be handed work by something else. Here is how to wire it into the git clients people actually use, and what to do when yours is not on the list.

Riffle Download Changelog

Start here

Install the command-line tool first

Every client below ends up calling the same riffle command. Riffle installs it for you, and none of it needs sudo.

01  Open the Integration settings

Riffle → Settings → Integration

One installer per integration, each with a live status and a copyable manual command if you would rather run it yourself.

02  Install the command line

/usr/local/bin/riffle

A symlink to the launcher inside Riffle.app. If /usr/local/bin is not writable it goes to ~/.local/bin and adds that to your PATH instead.

03  Install for git

git difftool · git mergetool

Writes the diff and merge entries into your global git config. Several GUI clients read those instead of keeping a tool list of their own.

Command line and git

One click

The riffle command follows the same grammar as ksdiff, so anything that can call a diff tool from a shell can call Riffle. The Git installer wires it into git itself, and the same command reviews a repository on its own.

  1. 01 In Riffle, open Settings → Integration and click Install beside Command Line, then beside Git.
  2. 02 Open a new terminal so the riffle command is picked up.
  3. 03 Run git difftool to see changes in Riffle, or git mergetool when a merge stops on a conflict.
  4. 04 Riffle becomes your default for both. Add -t riffle to either command if you would rather leave your defaults alone.
  5. 05 For a whole changeset rather than one file, run riffle diff in any repository. Add --watch and the window keeps itself current while you work.
  6. 06 No repository involved? riffle review --pairs list.json opens the same review over any set of before/after files a JSON file names — a build's outputs, a batch of generated files, or whatever your own script produces. With --watch, rewriting that file updates the window already open.

What the Git installer writes to your global git config

git config --global diff.tool riffle
git config --global difftool.riffle.cmd 'riffle --wait "$LOCAL" "$REMOTE"'
git config --global merge.tool riffle
git config --global mergetool.riffle.cmd 'riffle --merge --output "$MERGED" --base "$BASE" -- "$LOCAL" "$REMOTE"'
git config --global mergetool.riffle.trustExitCode true

Riffle blocks until you close the window, and reports what happened through its exit code: 0 when the merge is saved, 1 when you abort. That is what trustExitCode tells git to believe, so a merge you abandon does not get marked resolved.

Jujutsu (jj)

One click

jj has no diff view of its own to replace — it materializes a change's before and after trees and hands both to whatever tool you name. Riffle reads that pair as a folder comparison, so a change opens with every touched file laid out.

  1. 01 In Riffle, open Settings → Integration and click Install beside Jujutsu (jj). It configures jj through jj config set --user, so the entry lands wherever your jj config actually lives.
  2. 02 Run jj diff --tool riffle to see the working copy's change in Riffle, or any other revision with -r.
  3. 03 When a rebase or a squash leaves conflicts behind, jj resolve --tool riffle sends them to Riffle's merge window, file by file.
  4. 04 Prefer a patch view over config? Pipe it: jj diff --git | riffle opens the diff as a review, and needs no setup at all.

What the installer writes, if you would rather run it yourself

jj config set --user merge-tools.riffle.program riffle
jj config set --user merge-tools.riffle.diff-args '["--wait", "$left", "$right"]'
jj config set --user merge-tools.riffle.merge-args '["--merge", "--output", "$output", "--base", "$base", "--", "$left", "$right"]'

The trees jj hands over are temporary copies, so the comparison opens read-only — Riffle refuses to write into files jj is about to delete — and --wait is what keeps them alive until you close the window. Folder comparison is part of the paid tier.

Tower

One click

Tower keeps its own catalog of compare tools rather than reading your git config. Riffle writes itself into that catalog, along with a small launch script that covers both the 2-way and the 3-way case.

  1. 01 Quit Tower.
  2. 02 In Riffle, open Settings → Integration and click Install beside Tower. If the button is greyed out, launch Tower once so it creates its support folder, then come back.
  3. 03 Reopen Tower and go to Settings → Git Config.
  4. 04 Pick Riffle for both Diff Tool and Merge Tool.

Riffle writes into the catalogs for both Tower 3 and Tower 4, so upgrading does not lose the entry. If you move Riffle.app, reinstall from the same panel and the entry follows it.

Fork

Custom command

Fork ships a fixed list of built-in tools plus a Custom option. Point Custom at the riffle command and give it the arguments below.

  1. 01 Open Fork → Settings → Integration.
  2. 02 Set External Diff Tool to Custom, click Edit beside it, and use the two External Diff Tool rows below.
  3. 03 Set Merge Tool to Custom, click Edit beside that, and use the two Merge Tool rows below.
  4. 04 The two lines are not interchangeable, and the two dialogs look identical — Fork fills in $BASE and $MERGED only for the merge tool, so the merge line in the diff field means nothing happens at all.
  5. 05 Fork prefills the merge arguments with a plain four-path list that Riffle cannot read. Clear it and use the one below, -- included.
External Diff Tool → File Path
/usr/local/bin/riffle
External Diff Tool → Arguments
--wait $LOCAL $REMOTE
Merge Tool → File Path
/usr/local/bin/riffle
Merge Tool → Arguments
--merge --output $MERGED --base $BASE -- $LOCAL $REMOTE

Arguments go in Fork's single Arguments field, exactly as written here — Fork splits them on the spaces. If your riffle command lives somewhere else (~/.local/bin/riffle when /usr/local/bin is not writable), give the full path to it instead. Merging from Fork needs Riffle 2.0.7 or later: Fork clears its temporary files while the merge is still opening, and earlier versions read them too late.

Nothing happens when you click Merge in External Tool? Fork could not launch the file path — no error, no window, no clue. Check the path really runs: ls -l /usr/local/bin/riffle should point inside Riffle.app, and riffle --version should print a version. A symlink left behind by an older install, or one made while Riffle was running from the Downloads folder, is the usual culprit — reinstall the command line from Riffle's Settings → Integration to point it at the app's current home. Then quit Fork and reopen it: once a launch has failed, that button stays dead for the rest of the session, so fixing the path on its own looks like it changed nothing.

GitKraken

Git config

GitKraken only lists tools it ships built-in support for, and on macOS there is no field for a custom one. It does read your git config, and that is the way in.

  1. 01 Install the Git integration in Riffle first, from the panel at the top of this page. GitKraken reads diff.tool and merge.tool straight out of your global git config.
  2. 02 Open GitKraken → Preferences → External Tools.
  3. 03 Set External Merge Tool to Git Config Default.
  4. 04 Set External Diff Tool to Git Config Default as well.

Leave the diff tool on Git Config Default rather than <Use Merge Tool>. That option routes plain 2-way diffs through the merge command, which asks for a base and an output file a diff does not have.

Gitfox

Git config

Gitfox ships presets for a handful of tools and an Automatic option that reads your git config instead. Automatic is the one you want.

  1. 01 Install the Git integration in Riffle first, from the panel at the top of this page.
  2. 02 Open Gitfox → Settings → Integration.
  3. 03 Set both Difftool and Mergetool to Automatic. Gitfox then runs whatever diff.tool and merge.tool point at, which is Riffle.
  4. 04 Open a comparison from Repository → Open Diff or Mergetool.

Gitfox reads trustExitCode from the same config, so abandoning a merge leaves the conflict unresolved rather than marking it done. Its Use Directory Diff option works as well: handed two directories, Riffle opens a folder comparison, which is part of the paid tier.

SourceTree

Custom command

SourceTree keeps its own diff and merge settings and writes them back into your git config. Choose Custom in both and give it the command and arguments below.

  1. 01 Open SourceTree → Settings → Diff.
  2. 02 Under External Diff, set Diff Tool to Custom and fill in the first two rows.
  3. 03 Under Merge, set Merge Tool to Custom and fill in the last two rows.
Diff command
/usr/local/bin/riffle
Diff arguments
--wait "$LOCAL" "$REMOTE"
Merge command
/usr/local/bin/riffle
Merge arguments
--merge --output "$MERGED" --base "$BASE" -- "$LOCAL" "$REMOTE"

Anything else

General

Almost every client falls into one of two camps, and Riffle covers both.

  1. 01 If it offers a use my git config option, install Riffle's Git integration and pick that. GitKraken works this way, and so does anything built on git difftool and git mergetool.
  2. 02 If it offers a custom command, give it /usr/local/bin/riffle and the arguments below, substituting whatever token names it uses for the four paths.

The two commands, whatever the client calls them

# 2-way diff
riffle --wait "$LOCAL" "$REMOTE"

# 3-way merge, result written to $MERGED
riffle --merge --output "$MERGED" --base "$BASE" -- "$LOCAL" "$REMOTE"

Both forms block until you close the window and exit 0 on success, 1 on an abort, so a client that waits on its tool the way git does will follow along without any extra setup.

Wired something up that is not listed here? Send it over and it goes on the page.

← Back to Riffle