SyncFix

SyncFix is a Bash tool for resolving Syncthing conflict files (.sync-conflict-*) that accumulate when the same file is edited on multiple devices before they have a chance to sync. It walks your sync folders, surfaces each conflict pair with a diff, and lets you decide which version wins — or resolves everything automatically by timestamp.

Why

Syncthing never silently discards your work: when it detects a conflict it keeps both versions, renames the older one with a .sync-conflict-YYYYMMDD-HHMMSS-DEVICEID suffix, and leaves the resolution to you. In busy vaults (Logseq, Obsidian, Documents) these files pile up. SyncFix clears them safely: it never deletes both files in a pair, and a --dry-run mode lets you preview every decision before anything is touched.

Requirements

Standard utilities present on any modern Linux or macOS install:

Tool	Purpose
bash 4.0+	Shell (ships with Fedora, macOS via Homebrew)
find	Conflict discovery
stat	mtime comparison for --auto
diff	Side-by-side diff in interactive mode
mv, rm	File resolution

No external packages needed.

Installation

git clone <repo-url> ~/SyncFix
chmod +x ~/SyncFix/syncfix.sh

Optionally symlink onto your PATH:

ln -s ~/SyncFix/syncfix.sh ~/.local/bin/syncfix

Usage

./syncfix.sh [--dry-run] [--auto] [--log FILE] [--no-color] [paths...]

Flag reference

Flag	Description
--dry-run	Report all conflicts and what would happen; no files are changed
--auto	Keep the newer file by mtime; no interactive prompts
--log FILE	Append one tab-separated decision line per conflict to FILE
--no-color	Suppress ANSI color output (useful in scripts and CI)
paths...	One or more directories to scan recursively (see defaults below)

Default scan paths

When no paths are given, SyncFix scans the three configured Syncthing folders:

/home/sam/Sync              (folder ID: 37a8ee)
/home/sam/Documents/Library (folder ID: 67ffba)
/home/sam/Documents/logseq  (folder ID: 696448)

To scan a different set of directories, pass them as arguments:

./syncfix.sh /mnt/nas/shared ~/Documents/notes

Example output

Interactive mode (default)

--- diff ----
< original version
---
> conflict version
--- end  ----
original: /home/sam/Documents/logseq/daily/2026-05-16.md
conflict: /home/sam/Documents/logseq/daily/2026-05-16.md.sync-conflict-20260516-143022-LAPTOP.md
[k]eep original / [c]onflict wins / [s]kip (default=skip): c

3 conflict(s) found — 1 resolved, 2 skipped

Dry-run mode

$ ./syncfix.sh --auto --dry-run /home/sam/Documents/logseq

auto: conflict newer, overwriting original: /home/sam/Documents/logseq/daily/2026-05-16.md
auto: original newer, removing conflict:    /home/sam/Documents/logseq/projects/alpha.md...
auto: original newer, removing conflict:    /home/sam/Documents/logseq/pages/index.md...

3 conflict(s) found — 3 resolved, 0 skipped

No files were changed. Run without --dry-run to apply.

Orphan conflict (original missing)

Orphan conflict (original missing):
  /home/sam/Sync/archive/report.sync-conflict-20260101-090000-DESKTOP
[d]elete orphan / [s]kip (default=skip):

An orphan means the original was already deleted on another device. You can remove the leftover conflict file (d) or leave it alone (s).

Safety note

Always run --dry-run first when scanning a new folder. It shows exactly which files would be changed and in which direction, without touching anything.

./syncfix.sh --auto --dry-run ~/Documents/logseq

When you are satisfied with the preview:

./syncfix.sh --auto ~/Documents/logseq

SyncFix enforces a hard invariant in code: it will never rm both files in a conflict pair. If an unexpected state is detected before a deletion, it exits with code 2 and an error message rather than proceeding.

Exit codes

Code	Meaning
0	All conflicts processed (or none found)
1	Usage error (unknown flag, missing argument)
2	File operation error or safety guard triggered

Running the test suite

bash tests/test_syncfix.sh

Tests cover conflict discovery, suffix stripping, dry-run immutability, automatic resolution, the FR-10 safety guard, space-in-filename handling, and orphan detection.