Syncthing Deconflicter

A Rust-based tool that automatically resolves Syncthing conflicts on text files using Git's three-way merge algorithm. This tool monitors a directory tree and automatically handles .sync-conflict-* files by performing intelligent merges with the original file and backup versions.

Features

• 🔄 Recursive monitoring - Watches entire directory trees for conflicts
• ⚡ Low resource usage - Efficient Rust implementation with minimal memory footprint
• 🤖 Automatic resolution - No manual intervention required
• 📝 Git-powered merging - Uses git merge-file --union for intelligent conflict resolution
• 🎯 Text file focused - Designed for markdown, code, and other text-based files
• 📊 Verbose logging - Optional detailed output for monitoring and debugging
• 🚀 Server-ready - Perfect for headless server deployments

How It Works

1. Detection: Monitors directory for Syncthing conflict files (matching pattern *.sync-conflict-YYYYMMDD-HHMMSS-*.extension)
2. Analysis: Locates the original file and corresponding backup in .stversions/
3. Merging: Performs a three-way Git merge between:
   • Original file (current state)
   • Backup file (pre-conflict state from .stversions/)
   • Conflict file (divergent version)
4. Cleanup: Removes the conflict file after successful merge

Prerequisites

• Git must be installed and available in PATH
• Syncthing with versioning enabled (preferably "Simple File Versioning")
• Rust (for building from source)

Installation

From Source

# Clone the repository
git clone <repository-url>
cd syncthing-deconflicter

# Build optimized release binary for current platform
cargo build --release

# The binary will be available at
./target/release/syncthing-deconflicter

Cross-Platform Builds

To build for different platforms, you can use the cargo build command with the --target flag. Here are some common targets:

# Build for Windows (64-bit)
cargo build --release --target x86_64-pc-windows-gnu

# Build for macOS (Intel)
cargo build --release --target x86_64-apple-darwin

# Build for macOS (Apple Silicon)
cargo build --release --target aarch64-apple-darwin

# Build for Linux (64-bit)
cargo build --release --target x86_64-unknown-linux-gnu

# Build for Linux (ARM)
cargo build --release --target aarch64-unknown-linux-gnu

Note: You may need to install the necessary target toolchains using rustup target add <target>.

Usage

Basic Usage

# Monitor a directory
./syncthing-deconflicter /path/to/your/notes

# With verbose logging
./syncthing-deconflicter -v /path/to/your/notes

Command Line Options

Syncthing Deconflicter 0.1.0
Automatically handles Syncthing conflicts on text files using git three-way merge

USAGE:
    syncthing-deconflicter [OPTIONS] <NOTES_DIRECTORY>

ARGS:
    <NOTES_DIRECTORY>    Directory to watch for Syncthing conflicts

OPTIONS:
    -h, --help           Print help information
    -v, --verbose        Enable verbose output
    -V, --version        Print version information

Example Output

Normal mode:

Running Syncthing deconflicter
Watching directory recursively: /user/m/notes

🔧 Conflict file found: /user/m/notes/project/doc.sync-conflict-20241201-143022-ABCDEFG.md
📁 For original file: /user/m/notes/project/doc.md
📄 Latest backup file: .stversions/project/doc~20241201-142800.md
Performing three way merge with git command:
git merge-file --union /user/m/notes/project/doc.md .stversions/project/doc~20241201-142800.md /user/m/notes/project/doc.sync-conflict-20241201-143022-ABCDEFG.md
🗑️  Deleting conflict file
✅ Deconfliction done!

Verbose mode: Shows additional file system events and search operations.

Server Deployment

Systemd Service (Linux)

Create /etc/systemd/system/syncthing-deconflicter.service:

[Unit]
Description=Syncthing Deconflicter
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/path/to/syncthing-deconflicter /path/to/notes
Restart=always
RestartSec=10
WorkingDirectory=/path/to/notes

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable syncthing-deconflicter
sudo systemctl start syncthing-deconflicter
sudo systemctl status syncthing-deconflicter

Docker Deployment

Create a Dockerfile:

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/syncthing-deconflicter /usr/local/bin/
ENTRYPOINT ["syncthing-deconflicter"]

Build and run:

docker build -t syncthing-deconflicter .
docker run -v /path/to/notes:/notes syncthing-deconflicter /notes

Syncthing Configuration

For optimal results, configure Syncthing with:

1. File Versioning: Enable "Simple File Versioning"

   • Keep versions: 10+ (recommended)
   • This creates the .stversions/ directory needed for three-way merging

2. Folder settings:

   • Ensure the folder is configured for bidirectional sync
   • Consider setting "Folder Master" to false for all devices

Supported File Types

The deconflicter works best with text-based files:

• ✅ Markdown files (.md)
• ✅ Code files (.rs, .py, .js, etc.)
• ✅ Configuration files (.toml, .yaml, .json)
• ✅ Plain text files (.txt)
• ⚠️ Binary files will be processed but merging may not be meaningful

Troubleshooting

Common Issues

"No backup file candidates were found"

• Ensure Syncthing versioning is enabled
• Check that .stversions/ directory exists
• Try "Simple File Versioning" instead of other versioning types

"Git command failed"

• Verify Git is installed and in PATH
• Check file permissions
• Ensure the working directory is writable

High CPU usage

• Normal during active sync periods
• Use verbose mode to monitor file system events