Comparing & Merging

Iruka compares files and folders in a pane beside the file list, not in a popup window. Select two files and press ⌘⇧C, or use Compare in the right-click menu.

What the diff pane does

• Two files, side by side, with differences highlighted down to the changed words rather than just the changed lines.
• A file against git — against HEAD, against the index, or against any commit or branch.
• Review changes (⇧⌘U) — every changed file in the repository in a list beside the diff, with per-file staging, committing and discarding.
• Two folders, compared by inventory: what is only on the left, only on the right, and what exists on both but differs. This comparison is read-only — nothing in it moves a file.

⌘F searches inside the diff, and ⌘G steps through the matches.

Opening the comparison in another app

Iruka shows you the difference. Editing and merging it is a job other applications have spent years on, so there is a handoff button in the diff pane's header that opens the two files in one of them.

Choose which under Settings → General → Comparing.

The button only appears when the chosen tool was actually found. If it is missing, use Choose… to point Iruka at the program.

Worth knowing before you pick one

• Visual Studio Code and DiffMerge are free, so they are the quickest way to try this. VS Code needs its code command installed first — open the Command Palette and run Shell Command: Install 'code' command in PATH — or use Choose… and pick Visual Studio Code.app/Contents/Resources/app/bin/code.
• BBEdit opens three windows rather than one side-by-side comparison: one for each file, and a third listing the lines that differ. That is what bbdiff does; it is not a fault.
• Beyond Compare is bcomp, not bcompare. Its documentation writes switches with a leading slash (/title1=) — that is the Windows spelling. On macOS they take a dash, which is what Iruka's default uses.
• Araxis Merge installs its command-line utility inside the app bundle, at Contents/Utilities/compare, rather than on your PATH.
• FileMerge needs a full Xcode. The /usr/bin/opendiff on every Mac is a stub that refuses to run when only the Command Line Tools are installed, so Iruka hides the button rather than offering one that fails.

Why Iruka can't just find them. An app launched from the Dock has a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin), so compare, ksdiff and bcomp are invisible to it even when they work perfectly in Terminal. That is why Iruka checks known locations instead — and why Choose… is there when a tool lives somewhere else.

Arguments

The Arguments field is a template. Leave it empty to use the default for the chosen app.

Double quotes group words into a single argument. Nothing else is interpreted — there is no globbing, no shell variables, no $(…), and the program is launched directly rather than through a shell.

The defaults:

FileMerge, Kaleidoscope, BBEdit   "$LEFT" "$RIGHT"

Visual Studio Code                --diff "$LEFT" "$RIGHT"

DiffMerge                         --title1="$LTITLE" --title2="$RTITLE" "$LEFT" "$RIGHT"

Beyond Compare                    -title1="$LTITLE" -title2="$RTITLE" "$LEFT" "$RIGHT"

Araxis Merge                      -2 -title1:"$LTITLE" -title2:"$RTITLE" "$LEFT" "$RIGHT"

Note the three different separators — Araxis uses a colon, DiffMerge and Beyond Compare an equals. That is the vendors' choice, not Iruka's, and it is a good illustration of why this field is editable.

Why the titles matter

When you compare a file against git, the left-hand side does not exist as a file — it is a version inside the repository. Iruka writes it to a temporary file so the other application has something to open, which means that without a title flag the tool shows something like

/var/folders/9t/…/T/iruka-compare-4F2A…/Parser.swift

above the pane, instead of Parser.swift @ HEAD. Tools that accept title flags should have them in their template; tools that don't simply ignore the placeholders.

Editing the template

Presets are a starting point, not a promise. If a vendor changes a flag in a new version, or you want three-way merges, or you want the comparison window to block until you close it, edit the Arguments field — you do not need to wait for an Iruka release.

Some things you might want, and the flag that does it:

Araxis Merge      -3 …                    three-way comparison
Araxis Merge      -readonly1 …            left-hand side not editable
Beyond Compare    -ro1 …   (or -lro)      left-hand side not editable
DiffMerge         --title1= --title2=     already in the default
VS Code           --wait …                block until the tab is closed
BBEdit            --wait --resume …       block, and return focus afterwards
Kaleidoscope      -w …                    block until the window is closed

Each of these documents its own options — compare -h, man bbdiff, ksdiff --help and Beyond Compare's command line reference will tell you the rest.

The --wait family is deliberately not in any default. It makes the program sit there until you close the comparison window, which is right for a git mergetool and wrong here — Iruka opens the tool and gets out of the way.

If the tool exits with an error, Iruka shows you the message rather than doing nothing — a typo in a flag is the most likely cause once you start editing templates.

What Iruka does not do

• Three-way merges and conflict resolution. Iruka shows what changed; it does not resolve a merge. Hand the files to a tool that does.
• Folder synchronisation. Folder comparison tells you what differs; it will not copy or delete anything to make two folders match.