A fast, open-source desktop tool for comparing text, folders, tables, binaries and images, built with Tauri 2, SolidJS and Rust.
Native on Linux, Windows and macOS. Scriptable from the command line. Works as your git diff and merge tool.
Features · Download · Build from source · Command line · Git integration · Shortcuts · Project layout · Roadmap
Text Compare: line alignment, highlighting within lines, and important (red) vs. unimportant (blue) differences.
CompareCraft opens the right view for whatever you give it: two files, two folders, three files to merge, or a saved session.
|
Side-by-side diff with Standard (run-matching with closeness pairing and skew tolerance), Patience Diff,
Myers O(ND) or Unaligned line alignment, an optional never align differences mode, and highlighting
of changes within lines.
Differences are classified as important (red) or unimportant (blue): leading, trailing or embedded
whitespace, case, orphan lines, text replacements and sections you mark as Ignored. Gutter arrows
copy a section (or the selected lines) to the other side in one click. Align With and Isolate
fix up the alignment by hand. Edit inline, cut, copy and paste lines, compare a selection to the
clipboard, undo, and save each side on its own or both together. Saves keep the original encoding, BOM
and line endings, and write |
3-way merge (left, base, right → output). Non-conflicting changes merge automatically; for each conflict choose left, right, both or base. The output pane is editable, and conflict navigation takes you from one to the next. |
|
Recursive tree compare by timestamp & size, size, CRC32, binary or rules-based content.
A Filters bar ( |
Update left → right, right → left or both ways, or mirror in either direction. Every action is shown in a preview before anything runs, and syncing can be limited to the current selection. 3-way folder merge (left, base, right → output folder). Each file is classified as unchanged, a left or right
change, the same change or a conflict. Merge (Ctrl+M) copies the changed versions to the output; Take Left,
Take Right or a per-file Text Merge resolve conflicts. Start it from Home, |
|
Offsets, bytes and an ASCII column with difference navigation. Alignment (Complete, Fast or None) lines up matching data across inserted and deleted bytes, so an insertion shows as a gap instead of a run of differences. CSV/TSV with delimiter auto-detection, a header row, key columns for matching rows, and differences
shown cell by cell. Numbers compare by value ( |
Both pictures above a rendered difference picture. Tolerance mode marks unimportant differences blue and important ones red; mismatch range shades by size of difference; blend mixes the two. Offset, rotate, flip, auto-scale, zoom/fit and per-pixel colour details. Reads PNG, JPEG, GIF, BMP, TIFF, WebP, ICO, TGA, PNM, QOI and (through the webview) SVG/AVIF. Recent sessions are recorded automatically; Save Session / Save Session As… name them, Locked protects
them and Clear Session starts over. Reopen them from Home, the Sessions toolbar menu of each compare view,
or with Tools › Options covers startup and workspace, tabs, colours and fonts, text editing, next-difference
behaviour, backups, file-operation confirmations, keyboard shortcuts, Open With applications and tweaks.
There are also Export/Import Settings, Restore Factory Defaults, folder snapshots ( |
CompareCraft runs as a single instance: launching comparecraft a b again opens a new tab in the existing window. Light,
dark and auto themes are included.
-
User manual: https://antebios.github.io/comparecraft/. It is searchable and covers every view, the options, filters, the command line, scripting and reports.
-
In the app: press F1 (Help › CompareCraft Help) for the same manual, opened at the page for the current view, with full-text search (Ctrl+F). Help › Online Manual opens the website.
-
Source: the pages live in
docs/manual/and are built with MkDocs (Material theme) frommkdocs.yml:npm run docs:install # create .venv-docs and install documentation dependencies npm run docs:serve # live preview at http://127.0.0.1:8000 npm run docs:build # static site in site/
These commands use a project-local Python virtual environment; no activation or system-wide pip install is needed. Python 3 with
venvsupport is required (python3-venvon Debian/Ubuntu)..github/workflows/docs.ymlbuilds the site whenever the manual changes and publishes it to GitHub Pages frommain.One-time publishing setup: in the GitHub repository's Settings > Pages > Build and deployment, set Source to GitHub Actions, then rerun the docs workflow. A repository administrator must enable Pages; the workflow's built-in
GITHUB_TOKENcannot enable it automatically.
Installers for Linux (.deb, .rpm, AppImage), Windows (.msi, NSIS .exe) and macOS (.dmg, Apple Silicon
and Intel) are published on the releases page.
Arch / Omarchy: build and install the package from packaging/arch/PKGBUILD
(see below). On Omarchy, CompareCraft then appears in the app launcher (Super+Space).
Note
The downloads aren't code-signed yet. On Windows, if SmartScreen warns you, choose More info, then Run anyway. On macOS, the first time, right-click CompareCraft in Applications and choose Open.
All platforms need Rust (stable, via rustup) and Node.js ≥ 20.
Arch / Omarchy / Manjaro
sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl appmenu-gtk-module libappindicator-gtk3 librsvgDebian / Ubuntu / Pop!_OS / Mint
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-devFedora
sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file libappindicator-gtk3-devel librsvg2-devel
sudo dnf group install "c-development"Windows: Microsoft C++ Build Tools ("Desktop development with C++") and WebView2. WebView2 is preinstalled on Windows 10 (1803+) and 11.
macOS: Xcode Command Line Tools (xcode-select --install).
git clone https://github.com/Antebios/comparecraft.git
cd comparecraft
npm install
npm run app:dev # hot-reloading app
npm run typecheck # TypeScript
npm run test:rust # Rust unit tests + text, hex and picture golden suites
npm test # typecheck + Rust tests
npm run parity # command-line exit-code and merge-output checks (needs a release build)
npm run ccomp -- @script.txt a b # run the console version (ccomp) from sourcenpm run app:build # all bundle types for the host OS
npm run app:build:bin # release binaries (comparecraft, ccomp), no installers
npm run app:build:linux # deb, rpm, AppImage
npm run app:build:windows # NSIS, MSI
npm run app:build:macos # .app, .dmgnpm run tauri -- <args> passes any other Tauri CLI arguments through.
Installers go to src-tauri/target/release/bundle/. The bare binaries are src-tauri/target/release/comparecraft
(the application) and src-tauri/target/release/ccomp (the console version).
-
Arch / Omarchy:
npm run package:arch # or: cd packaging/arch && makepkg -sfiThis rebuilds the package from the current checkout, even when an archive with the same version already exists. Close any running CompareCraft instances before launching the newly installed version.
-
Desktop entry: the Arch package installs
packaging/linux/comparecraft.desktop; the.deb,.rpmand AppImage bundles generate their own.
.github/workflows/build.yml runs the type check and Rust tests on every push
and pull request. Pushing a v* tag builds installers for Linux, Windows and macOS (Intel and Apple Silicon)
and attaches them to a draft release.
comparecraft [options] [left] [right] [center] [output]
comparecraft a.txt b.txt # text compare (viewer chosen by file type)
comparecraft dirA dirB # folder compare (-sync for folder sync)
comparecraft mine.txt theirs.txt base.txt out.txt # 3-way merge
comparecraft -fv="Hex Compare" a.bin b.bin
comparecraft -qc a.txt b.txt; echo $? # quick compare, no GUI
comparecraft -qc=binary|crc|size a b
comparecraft -automerge [-force] [-iu] [-reviewconflicts] mine theirs base -mergeoutput=out
comparecraft -filters="*.rs;-target/" -expandall dirA dirB
comparecraft "My saved session"
comparecraft @nightly.txt dirA dirB -silent # run a script without the GUI
comparecraft -cc-select-left a.txt # stage a file for a later context-menu comparison
comparecraft -cc-compare-staged b.txt # compare b.txt to the staged left file
comparecraft -cc-compare a.txt b.txt # compare two selected files
Switches use -name[=value]; on Windows /name[=value] also works. Run comparecraft -h for the full list.
On Windows, Linux and macOS, Tools → Options → Startup → File manager integration adds or removes CompareCraft
actions for the current user. This does not require administrator privileges. Windows registrations are stored in
the current user's Explorer classes; Linux actions are installed for Nautilus (Files), Dolphin and Thunar.
The app installer migrates existing registrations to the current command format and removes them when
uninstalled. A fresh Windows NSIS install enables the actions by default; existing choices are preserved during
upgrades, and the actions can be enabled or removed in Options. Linux actions remain opt-in.
On Windows, if the installer cannot refresh the registrations, it writes the failure exit code to
shell-integration-install-error.txt in the installation directory. The Options checkboxes reflect
enabled preferences, even when an action is temporarily hidden for the current selection.
Enable the file and folder actions separately. Select Left File for Compare remembers a file; Select Left Folder for Compare remembers a folder independently. Selecting Left again replaces only that kind of selection. Compare to Selected Left File/Folder appears only for one matching right item and a valid, different left path. Select Left stays available after staging. Clear Selected Left File/Folder clears only that kind of selection. A successful staged comparison consumes its own selection; direct two-item actions leave both selections intact. Deleted or invalid left paths are treated as unstaged.
| Selection | Enabled actions offered |
|---|---|
| One file | Select Left File; matching Compare to Selected Left and Clear when staged |
| One folder | Select Left Folder; matching Compare to Selected Left and Clear when staged |
| Two files | Compare, Merge |
| Two folders | Compare, Sync |
| Nothing, mixed types, or more than two items | None |
Sync opens the existing synchronization interface, not an immediate copy operation. Folder Merge requires a base folder and is not offered for two folders. Direct comparisons preserve the file manager's supplied order; use Swap Sides when necessary. Staged comparisons explicitly preserve left/right order.
Linux uses native providers: GNOME Files needs nautilus-python; Thunar and Dolphin need their packaged
Thunarx/KIO providers. The Arch package builds and installs all three. Ubuntu 22.04 CI bundles include
Thunar (built with libthunarx-3-dev and pkg-config), but omit the Dolphin plugin because that runner
does not provide KDE Frameworks 6. The CI job applies
the Ubuntu bundle override; use
npm run app:build:linux -- --config src-tauri/tauri.ubuntu-22.04.conf.json for the same bundle configuration
on Ubuntu 22.04 after installing those development packages. The default Linux configuration still bundles
the Dolphin plugin and requires Qt 6/KDE Frameworks 6 development packages to build it.
Rebuild/reinstall the package, enable
the desired actions in Options, and restart each file manager after installing or updating its native provider.
For Thunar, finish any file operations, run thunar --quit, then reopen it with thunar.
This closes all Thunar windows and its background daemon; closing a window alone may leave the old daemon
running without the new provider. No rebuild is needed if the updated package is already installed.
See missing context-menu commands.
Files actions now appear in the normal context menu, not Scripts. Applying Options removes the old
CompareCraft scripts, service menus and custom-action block without touching unrelated actions.
Native menus re-evaluate selection and staged state when opened. Action icons are supplied where the host
supports them; appearance depends on the installed icon theme and file-manager version. On Windows 11,
Explorer may place the commands under Show more options. macOS now includes an experimental Finder Sync
extension; native activation, signing, sandbox access and launch behavior still need testing on real Macs.
Run npm run test:menus on Linux to build and test native menu callbacks. The native Windows provider
also needs validation in Explorer on Windows; a Linux type-check is not a Windows runtime test.
If an older installer has already been removed, its uninstaller cannot remove the registry entries because that older build did not include a cleanup hook. Installing this build migrates the entries; uninstalling this build removes them. To remove them immediately without reinstalling, run this PowerShell command as the same Windows user:
$root = 'Registry::HKEY_CURRENT_USER\Software\Classes\*\shell'
Get-ChildItem -LiteralPath $root -ErrorAction SilentlyContinue |
Where-Object { $_.PSChildName -like 'CompareCraft.*' } |
Remove-Item -Recurse -Force
Remove-Item -LiteralPath 'Registry::HKEY_CURRENT_USER\Software\Classes\Directory\shell\CompareCraft.sync' -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath 'Registry::HKEY_CURRENT_USER\Software\Classes\CLSID\{5E8A1F31-92B3-4B16-A421-724E3F8C1001}' -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath 'Registry::HKEY_CURRENT_USER\Software\Classes\CLSID\{5E8A1F32-92B3-4B16-A421-724E3F8C1002}' -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath 'Registry::HKEY_CURRENT_USER\Software\Classes\CLSID\{5E8A1F33-92B3-4B16-A421-724E3F8C1003}' -Recurse -Force -ErrorAction SilentlyContinueThe macOS build embeds CompareCraftFinder.appex in the application bundle for both Apple Silicon and Intel.
Finder Sync requires macOS 12 or later and a complete .app installation, not a bare binary or tauri dev.
Move CompareCraft to /Applications, open it, enable the desired actions in Options, and enable CompareCraft
in System Settings under Extensions / Finder Extensions. On recent versions this is under General > Login
Items & Extensions; the exact location varies. Options registers the extension but does not enable it without
your consent. The default scope is your home directory and mounted volumes under /Volumes, not every system
directory. Files and folders share the same selection rules as the other native integrations. Menu icons use
SF Symbols where available. Finder activation does not require restarting after each staged selection.
The sandboxed extension and host share the group.dev.comparecraft.app App Group. Local builds are ad-hoc
signed for compilation checks; this does not guarantee macOS will allow extension activation or App Group
access. Properly authorized signing identities and provisioning profiles may be necessary. Do not disable SIP,
Gatekeeper, or the sandbox to work around signing errors.
Developers/testers: see macOS Finder setup and test checklist. Run
npm run test:finder on a Mac with Xcode; PR macOS build jobs compile the universal extension and run native
menu-model tests, but they cannot verify interactive Finder behavior. Linux checks validate the portable Rust
snapshot and plist contracts only. Build and CI success are not a claim of native runtime verification.
Manual Quick Actions remain available if Finder Sync cannot be activated. They are not registered by Options and do not provide dynamic type/count/staged-state filtering. They can be created per-user in Automator without administrator privileges:
- Create a Quick Action that receives files in Finder and add Run Shell Script with “Pass input: as arguments”.
- For a Select Left File for Compare action, use
"/Applications/CompareCraft.app/Contents/MacOS/comparecraft" -cc-select-left "$1". - For a Compare to Selected Left File action, use
"/Applications/CompareCraft.app/Contents/MacOS/comparecraft" -cc-compare-staged "$1". - For a Compare action that accepts multiple files, use
"/Applications/CompareCraft.app/Contents/MacOS/comparecraft" -cc-compare "$@".
Adjust the executable path if CompareCraft is installed outside /Applications. The staged-left action is
shared across platforms and survives separate Finder invocations. To remove a Quick Action, delete its workflow
from ~/Library/Services. Quick Action titles are static; macOS does not dynamically include the staged file's
name in the menu item.
comparecraft is a single-instance GUI program. When CompareCraft is already running, a new comparison opens
as a tab in that window and the command returns immediately. On Windows it has no console, so script and
quick-compare output is not shown.
ccomp (ccomp.exe on Windows) is the console version and is installed next to comparecraft. It takes the
same arguments:
- Scripts (
@script.txt),-qc,-automergeand-hrun insideccompand print to the console. The exit code is the result. - Any other request opens a new CompareCraft window, and
ccompwaits until that window is closed. This makes it the command to use in batch files, build scripts and version control tools.
ccomp @nightly.txt dirA dirB # script output in the console, exit code = result
ccomp -qc a.txt b.txt # quick compare
ccomp a.txt b.txt && echo "closed" # waits for the compare window to closeccomp looks for comparecraft in its own folder, then on the PATH. Set COMPARECRAFT_GUI to the
application's path to override this.
Exit codes for quick compare and automerge:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Binary same |
| 2 | Rules-based same (only encoding, BOM or line-ending differences) |
| 11 | Binary differences |
| 12 | Similar (only unimportant differences) |
| 13 | Rules-based differences |
| 14 | Conflicts detected (-force output written) |
| 100 | Error (missing or invalid arguments) |
| 101 | Conflicts detected, merge output not written |
| 102 | ccomp could not wait for the CompareCraft window to close |
| 103 | ccomp could not find or start the CompareCraft application |
A script is a text file with one command per line. Run it with ccomp @script.txt [params] [-silent] (or
comparecraft @script.txt ...). The GUI does not open, the log is echoed to the console unless -silent is
given, and the exit code reports the result.
Commands are case-insensitive, # starts a comment and a trailing & continues a line. Quote paths that contain
spaces. %1..%9 are the script parameters, and %date%, %time% and %fn_time% expand to the current date
and time. Any other %NAME% is replaced by that environment variable.
# nightly.txt: compare two folders, sync newer files and write reports
log verbose "logs/%date%_%fn_time%.txt"
option confirm:yes-to-all
criteria timestamp:2sec size
filter "*.rs;*.toml;-target/" cutoff:<30days
load "%1" "%2"
expand all
folder-report layout:side-by-side options:display-mismatches,column-size output-to:report.html output-options:html-color
select left.newer.files left.orphan.files
copy left->right
sync update:left->right
text-report layout:patch options:patch-unified output-to:changes.diff "%1/README.md" "%2/README.md"
| Command | Purpose |
|---|---|
log [none|normal|verbose] [[append:]file] |
Write a time-stamped log of every command and file operation |
load <left> <right> / load <session> / load <default> |
Load a folder or file comparison (create:left|right|all creates missing folders) |
criteria, filter, option |
Comparison criteria (timestamp[:Nsec][;IgnoreDST], size, crc, binary, rules-based), name masks, cutoff:/size: filters, stop-on-error, confirm: |
expand, collapse, select |
Choose folders and items, e.g. select left.orphan.files, select all.diff.files, select empty.folders |
compare [crc|binary|rules-based] |
Re-compare the selected files |
copy, move, copyto, moveto, delete, rename, touch, sync, snapshot |
File operations on the selection (rename accepts masks like *.bak or regexpr <old> <new>) |
folder-report, file-report, text-report, hex-report, data-report, table-report, picture-report |
Plain-text, HTML or XML reports with layout:, options:, title:, output-to: (a file, printer or clipboard) and output-options: |
A script name without a folder is also looked up in the Scripts folder of the data location.
| Code | Meaning |
|---|---|
| 0 | Script completed |
| 100 | An error occurred and option stop-on-error was set |
| 105 | The script file could not be loaded |
| 106 | Unknown command or invalid arguments |
| 107 | A comparison could not be loaded |
git config --global diff.tool comparecraft
git config --global difftool.comparecraft.cmd 'ccomp "$LOCAL" "$REMOTE"'
git config --global merge.tool comparecraft
git config --global mergetool.comparecraft.cmd 'ccomp "$LOCAL" "$REMOTE" "$BASE" "$MERGED"'
git config --global mergetool.comparecraft.trustExitCode trueThen use git difftool and git mergetool as usual.
Every view has a menu bar (Session / File / Edit / Search / View / Tools / Help; Folder Compare has Actions instead of File). Right-click, the Menu key or Shift+F10 opens the context menu for the selection. Press F1 for help on the current view, Shift+F1 for the full list of shortcuts in the current view, or F10 to work the menus from the keyboard. On macOS, Ctrl means ⌘. Shortcuts can be changed in Tools › Options › Toolbars, Shortcuts.
| Key | Action |
|---|---|
| Ctrl+T / Ctrl+W / Ctrl+Tab | New tab / close tab / next tab (Shift+Ctrl+Tab: previous tab) |
| Alt+Home, Ctrl+Q | Home view, exit |
| Ctrl+N / Ctrl+P | Next / previous difference (all views) |
| Alt+N / Alt+P | Next / previous conflict (Text Merge) |
| Ctrl+L / Ctrl+R | Copy to left / right (Text and Folder Compare); take left / right (Merge) |
| Shift+Ctrl+L / Shift+Ctrl+R | Copy line (Text Compare); mirror to left / right (Folder Compare) |
| Ctrl+B / Shift+Ctrl+B | Take left then right / right then left (Merge) |
| Ctrl+F, F3, Shift+F3 | Find, find next, find previous |
| Ctrl+G | Go to line (Text) / go to offset (Hex) |
| Alt+↑ / Alt+↓ / Alt+← / Alt+→ | Previous / next existing line, go left / right (Text Compare) |
| F2, Ctrl+Enter, Del | Edit line, insert line, delete line (Text Compare) |
| F7, Ctrl+D, Shift+↑ / Shift+↓ | Align with, select section, extend line selection (Text Compare) |
| Shift+Ctrl+I / Shift+Ctrl+U | Increase / decrease indent (Text Compare) |
| Shift+Ctrl+V, F12 | Open clipboard, save file as (Text Compare) |
| Ctrl+S, Shift+Ctrl+S | Save file, save session |
| Ctrl+Z, Ctrl+Y | Undo, redo |
| F5, Ctrl+F5 | Refresh / reload, full refresh / recompare |
| Enter (Folder Compare) | Open the selected pair, or open/close a single folder |
| F2, Ins, Del, Shift+Del (Folder Compare) | Rename, new folder, delete (to trash), delete permanently |
| F6, F7, Shift+F5 (Folder Compare) | Align with, compare to, refresh selection |
| Alt+← / Alt+→ (Folder Compare) | Back / forward through base-folder history |
| Ctrl+← / Ctrl+→ (Folder Compare) | Act on the left / right side of the selected rows |
| ↑ ↓ PgUp PgDn Home End, ← → (Folder Compare) | Move selection (add Shift to extend it), collapse / expand folder |
| Ctrl+A, Shift+Ctrl+A (Folder Compare) | Select all, select all files |
| Ctrl+Alt+L (Folder Compare) | Legend |
| Ctrl+1 / Ctrl+2 / Ctrl+3 (Folder Compare) | Show all / differences / same |
| Ctrl+1 / Ctrl+2 / Ctrl+3 (Picture Compare) | Tolerance / mismatch range / blend mode |
| F8, Ctrl++ / Ctrl+− / Ctrl+0 (Picture Compare) | Blend toggle, zoom in / out / actual size |
Sessions are stored in sessions.json and options in settings.json in:
- Linux:
~/.config/comparecraft/ - macOS:
~/Library/Application Support/comparecraft/ - Windows:
%APPDATA%\comparecraft\
Set COMPARECRAFT_CONFIG_DIR to use a different folder.
index.html frontend entry point (Vite)
src/ SolidJS UI: app shell, store, menus, views/*
src-tauri/src/
fileio.rs encoding/BOM/EOL detection, safe saves with backups
align.rs alignment engine: Standard, Patience, Myers, Unaligned
diff.rs importance rules, line status, in-line highlighting
merge.rs 3-way merge
quick.rs -qc quick compare and exit codes
folder.rs folder scan, compare criteria, masks, file operations, sync plan/execute
folder_merge.rs 3-way folder merge classification
hex.rs hex compare with byte alignment
pix.rs picture decoding, statistics and difference rendering
table.rs table compare
sessions.rs session persistence
settings.rs options file, settings export/import
snapshot.rs folder snapshots (.ccsnap)
shell.rs native file-manager integration and preferences
shell/finder.rs experimental Finder Sync registration and shared menu state
cli.rs argument parsing, automerge
script.rs @script runner: commands, selection, file operations, logging
report.rs folder, file, text, hex, table and picture reports (text, HTML, XML), used by scripts and the GUI
lib.rs Tauri commands, single-instance forwarding
main.rs application entry point (comparecraft)
console.rs console version (ccomp): headless requests in the console, waits for GUI windows
src/help/ in-app help: renders and searches docs/manual
docs/manual/ user manual (Markdown) and its images, also used by this README
mkdocs.yml manual website configuration and navigation
packaging/ Arch PKGBUILD, Linux .desktop file
scripts/parity.sh command-line exit-code and merge-output checks
tests/fixtures/ quick-compare and merge test files
src-tauri/tests/ golden cases for the engines, reports and scripts (fixtures/engine, hex, pix, script)
CompareCraft is early but usable (version 0.1). Text, merge, folder, sync, hex, table and picture comparison all
work, scripts can run comparisons, file operations and reports without the GUI, and the command-line exit codes are
covered by scripts/parity.sh.
Not implemented yet:
- folder merge and three-way folder compare
- source-control integration
- media, registry and version-information compare; picture metadata compare
- archives as folders; FTP/SFTP and cloud locations
Bug reports and pull requests are welcome in GitHub issues.
MIT © 2026 CompareCraft contributors
CompareCraft is an independent project and is not affiliated with, sponsored by, or endorsed by Scooter Software, Inc. Beyond Compare is a trademark of Scooter Software, Inc.







