Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (77 loc) · 3.58 KB

CLAUDE.md

File metadata and controls

104 lines (77 loc) · 3.58 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

Build & Development Commands

Building

# Development build
cargo build

# Optimized release build
cargo build --release

# Cross-platform builds
cargo build --release --target x86_64-pc-windows-gnu  # Windows 64-bit
cargo build --release --target x86_64-apple-darwin    # macOS Intel
cargo build --release --target aarch64-apple-darwin    # macOS Apple Silicon
cargo build --release --target x86_64-unknown-linux-gnu  # Linux 64-bit

Running

# Run the built binary
./target/release/syncthing-deconflicter /path/to/directory

# Run with verbose logging
./target/release/syncthing-deconflicter -v /path/to/directory

Testing

No specific test commands are configured in this project.

Architecture

Core Components

The application consists of a single file src/main.rs with the following key components:

  1. File Monitoring (main()):

    • Uses notify crate for recursive file system monitoring
    • Sets up a channel-based event system for file changes
    • Watches for file modifications and creations

  2. Event Handling (handle_file_event()):

    • Processes file system events
    • Handles both Modify and Create events with appropriate delays for Syncthing
    • Delegates conflict detection and merging

  3. Conflict Detection (merge_if_applicable()):

    • Uses regex pattern matching to identify Syncthing conflict files
    • Pattern: ^(.*?)(?:\.|%2F)sync-conflict-([0-9]{8})-([0-9]{6})-(.{7})\.?(.*)$
    • Locates original files and corresponding backup files in .stversions/

  4. Three-Way Merge (merge_files()):

    • Executes git merge-file --union command
    • Uses original file, backup file, and conflict file for merging
    • Handles merge errors and cleanup

Key Dependencies

  • notify - File system monitoring
  • clap - Command line argument parsing
  • regex - Pattern matching for conflict files
  • log + simplelog - Logging infrastructure
  • tokio - Async runtime for event handling

Working Flow

  1. Monitor directory for file system events
  2. Detect Syncthing conflict files by regex pattern
  3. Locate original file and latest backup in .stversions/
  4. Perform three-way merge using Git's merge-file command
  5. Remove conflict file after successful merge
  6. Log operations and errors appropriately

Important Patterns

  • Conflict File Pattern: Files matching *.sync-conflict-YYYYMMDD-HHMMSS-*.extension
  • Backup File Location: .stversions/ directory with pattern original~YYYYMMDD-HHMMSS.extension
  • Merge Strategy: Git union merge preserves all changes from both versions
  • Timing: Includes 100ms delays to handle Syncthing's temporary file operations

Error Handling

The application handles various error scenarios:

  • Invalid UTF-8 paths
  • Missing original files
  • Missing backup files
  • Git command failures
  • File system permission issues
  • Invalid regex patterns

Deployment Considerations

  • Designed for headless server deployment
  • Can be run as a systemd service
  • Minimal resource usage with efficient file system monitoring
  • Requires Git to be installed and available in PATH
  • always run app with cargo run, read the errors and fix them