Two files, one diff.

Launching diff

Press F9 (or click F9 Diff in the function-key bar) to compare two files. Select both in one pane with Space or ⌘-click, or put the cursor on a file in each pane.

You can also choose Tools → Compare Files… (it’s in the Edit menu too). Compare Files works on files only — if you select folders, Captain’s Deck tells you to pick two files instead. To compare folders, see Comparing folders below.

Use your favourite compare tool

Compare Files opens the built-in diff by default. To use another app, go to Settings → External Tools and pick a Compare tool:

• Built-in Visual Diff — the default, described on this page.
• FileMerge — Apple’s compare app. It comes with Xcode.
• Kaleidoscope (ksdiff) and Beyond Compare (bcomp) — these need the app’s command-line tool installed.
• Custom Command — type any command in the Command field. {left} and {right} are replaced with the two file paths, for example /usr/local/bin/mydiff {left} {right}.

If Kaleidoscope or Beyond Compare isn’t installed, or the custom command is empty, Captain’s Deck tells you and offers to use the built-in diff instead.

The diff window

The built-in Visual Diff window shows the left file and the right file side by side, with added, removed and changed lines highlighted. Both sides scroll together, and the status line shows how many lines were added and removed and how many hunks there are.

• ◀ Previous / Next ▶ — jump to the previous / next change
• n / p — next / previous hunk (see below)
• Close — close the window

Merging changes

The diff viewer groups consecutive changed lines into hunks — one block of related changes. Use these keys to walk through them and decide each one:

• n — next hunk
• p — previous hunk
• > — take right: the left file adopts the right side’s version of this hunk
• < — take left: the right file adopts the left side’s version
• x — skip this hunk (both files stay as they are)

Merge single lines. You don’t have to take a whole hunk. Select one or more lines on either side, then click Take Left or Take Right in the toolbar (or press < / >) to copy just those lines across. With nothing selected, the buttons and keys act on the current hunk.

Decisions are kept in memory until you commit them. The status bar shows the current hunk number and which way (if any) you’ve resolved it.

When you’re happy, click Save Merged in the toolbar (it stays greyed out until you’ve made at least one decision). Captain’s Deck writes both files at once (only the side you actually changed gets touched) and re-runs the diff so you can see the new state. Close the panel without saving and nothing is written.

Your files stay as they were. Each file is saved back in its own text encoding (UTF-8, Latin-1, Windows Greek and so on) and with its own line endings, so a merge only changes the lines you merged. A file Captain’s Deck can’t write back exactly as it found it — one that isn’t text it recognises, or that mixes Windows and Mac line endings — opens read-only, and the status bar says why. You can still read the differences and take changes into the other file.

Comparing folders

F9 compares files, not folders. To compare two folders, point the left and right panes at them and choose Tools → Folder Sync…. It lists which files exist only on one side and which differ, and lets you copy them across in either direction.

See Folder Sync for the full walkthrough.