WatchDiff 🔭

A professional-grade file watcher with beautiful TUI, multiple diff algorithms, and comprehensive patch export capabilities, written in Rust.

Features

Core Capabilities

• 🚀 High Performance: Built with Rust for maximum speed and efficiency
• 🎨 Beautiful TUI: Rich terminal interface with scrollable diff log and file list
• 🌈 Syntax Highlighting: Full syntax highlighting for 25+ programming languages in diffs
• 📂 Smart Filtering: Respects .gitignore patterns automatically
• 🔍 Real-time Diffs: Shows beautiful diffs for text file changes as they happen
• ⌨️ Easy CLI: Multiple output formats and intuitive keyboard shortcuts
• 🧵 Async: Non-blocking file watching with threaded architecture

Advanced Features

• 🔧 Multiple Diff Algorithms: Choose from Myers, Patience, or LCS algorithms
• 📤 Patch Export: Export changes as unified diffs, Git patches, or multifile bundles
• 📊 Rich Statistics: Comprehensive diff statistics with addition/deletion ratios
• 🏗️ Modular Architecture: Clean separation of concerns with trait-based design
• 🎯 Professional Tools: Enterprise-grade patch management and export functionality

Installation

From Cargo

cargo install watchdiff-tui

Build from Source

git clone git@github.com:xicv/watchdiff.git
cd watchdiff
cargo build --release
./target/release/watchdiff

Usage

Basic Usage

# Watch current directory with TUI
watchdiff-tui

# Watch specific directory
watchdiff-tui /path/to/project

# Watch with text output
watchdiff-tui --output text

# Watch only specific file types
watchdiff-tui --extensions rs,py,js

# JSON output for scripting
watchdiff-tui --output json

Advanced Usage

# Use different diff algorithms
watchdiff-tui --algorithm myers     # Fast, general purpose (default)
watchdiff-tui --algorithm patience  # Better for refactored code
watchdiff-tui --algorithm lcs       # Minimal diffs

# Export patches while watching
watchdiff-tui --export-dir ./patches /path/to/project

# Combine algorithm and export
watchdiff-tui --algorithm patience --export-dir ./patches

User Interface

TUI Mode (Default)

WatchDiff features a modern, responsive terminal user interface built with ratatui. The interface is designed for maximum productivity and ease of use.

Interface Layout

┌─────────────────────────────────────────────────────────────────────────┐
│ Changes (↑↓ to scroll, PgUp/PgDn, Home/End)                           │
├─────────────────────────────────────────────────────────────────────────┤
│ [12:34:56] MODIFIED src/main.rs                                        │
│ --- src/main.rs                                                         │
│ +++ src/main.rs                                                         │
│ @@ -15,7 +15,8 @@                                                      │
│ - fn main() {                                                           │
│ + fn main() -> Result<()> {                                            │
│     let cli = Cli::parse();                                            │
│ +   println!("Starting WatchDiff...");                                │
│                                                                         │
│ [12:34:52] CREATED docs/api.md                                          │
│ Preview:                                                                │
│   # API Documentation                                                   │
│   This document describes the WatchDiff API...                         │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│ Watched Files (847) (←→ to scroll)                                     │
├─────────────────────────────────────────────────────────────────────────┤
│ src/main.rs                                                             │
│ src/lib.rs                                                              │
│ src/cli.rs                                                              │
│ src/watcher.rs                                                          │
│ src/diff.rs                                                             │
│ src/tui.rs                                                              │
│ ...                                                                     │
├─────────────────────────────────────────────────────────────────────────┤
│ Status                                                                  │
├─────────────────────────────────────────────────────────────────────────┤
│ Press q to quit, h for help, ↑↓ to scroll diff                        │
│ Events: 23 | Files watched: 847                                        │
└─────────────────────────────────────────────────────────────────────────┘

Panel Breakdown

📊 Top Panel - Changes Log (70% height)

• Real-time scrollable feed of file changes
• Color-coded event types:
  • 🟢 CREATED - New files (green)
  • 🟡 MODIFIED - Changed files (yellow)
  • 🔴 DELETED - Removed files (red)
  • 🔵 MOVED - Renamed/moved files (blue)
• Full syntax highlighting for 25+ languages including:
  • Rust, Python, JavaScript, TypeScript, Java, C/C++, Go
  • HTML, CSS, JSON, YAML, TOML, XML, Markdown
  • Bash, SQL, Dockerfile, and many more
• Unified diff format with intelligent syntax preservation
• Timestamps for each event
• Syntax-highlighted content preview for new files
• Scrollbar for long change lists

📁 Middle Panel - File List (25% height)

• Live list of all watched files
• File count indicator
• Alternating row colors for readability
• Horizontal scrolling for long paths
• Respects .gitignore patterns

ℹ️ Bottom Panel - Status Bar (5% height)

• Real-time statistics (event count, file count)
• Keyboard shortcuts reminder
• Application status indicators

Visual Features

• Color Coding: Intuitive colors for different change types
• Responsive Layout: Adapts to terminal size changes
• Smooth Scrolling: Efficient scrolling through large change logs
• Typography: Clear, readable text with proper spacing
• Borders: Clean visual separation between panels
• Icons: Unicode symbols for better visual hierarchy

Keyboard Shortcuts

Help Screen

Press h or F1 to open the interactive help screen:

┌─────────────────────────────────────────────────────────────────────────┐
│ Help                                                                    │
├─────────────────────────────────────────────────────────────────────────┤
│ WatchDiff - File Watching Tool                                         │
│                                                                         │
│ Keyboard Shortcuts:                                                     │
│                                                                         │
│   q, Esc      - Quit the application                                   │
│   h, F1       - Show/hide this help                                    │
│   ↑, k        - Scroll diff log up                                     │
│   ↓, j        - Scroll diff log down                                   │
│   PgUp        - Scroll diff log up (fast)                              │
│   PgDn        - Scroll diff log down (fast)                            │
│   Home        - Go to top of diff log                                  │
│   End         - Go to bottom of diff log                               │
│   ←, →        - Scroll file list                                       │
│                                                                         │
│ Features:                                                               │
│                                                                         │
│ • Real-time file change monitoring                                      │
│ • Respects .gitignore patterns                                          │
│ • Shows diffs for text file changes                                     │
│ • Scrollable diff log and file list                                     │
│ • High performance with async processing                                │
└─────────────────────────────────────────────────────────────────────────┘

Alternative Output Modes

For non-interactive use cases, WatchDiff supports several output formats:

Text Mode (--output text)

$ watchdiff-tui --output text
Watching: /home/user/project
Press Ctrl+C to quit
---
[12:34:56] MODIFIED src/main.rs
  - fn main() {
  + fn main() -> Result<()> {
      let cli = Cli::parse();
  +   println!("Starting WatchDiff...");

[12:34:52] CREATED docs/README.md

JSON Mode (--output json)

{"path":"src/main.rs","kind":"Modified","timestamp":{"secs_since_epoch":1703932496,"nanos_since_epoch":0},"diff":"--- src/main.rs\n+++ src/main.rs\n@@ -1,3 +1,4 @@\n-fn main() {\n+fn main() -> Result<()> {\n     let cli = Cli::parse();\n+    println!(\"Starting WatchDiff...\");","content_preview":null}

Compact Mode (--output compact)

$ watchdiff-tui --output compact
M src/main.rs
C docs/README.md  
D old_file.txt

Format Legend:

• C = Created
• M = Modified
• D = Deleted
• V = Moved

CLI Options

Options:
  -m, --mode <MODE>           File watching mode [auto|native|polling]
      --max-events <N>        Maximum events to store [default: 1000]  
  -v, --verbose              Enable verbose logging
      --no-color             Disable colored output
      --extensions <EXTS>    File extensions to watch (e.g., rs,py,js)
      --ignore <PATTERNS>    Additional patterns to ignore
      --context <N>          Number of diff context lines [default: 3]
      --output <FORMAT>      Output format [tui|json|text|compact]
      --poll-interval <MS>   Polling interval in ms [default: 1000]
      --algorithm <ALG>      Diff algorithm [myers|patience|lcs] [default: myers]
      --export-dir <DIR>     Export patches to directory (TUI mode only)

Diff Algorithms

WatchDiff supports multiple diff algorithms, each optimized for different scenarios:

Export Functionality

When using --export-dir, WatchDiff automatically saves patches in multiple formats:

• Unified diffs (.patch files) - Standard diff format
• Git patches (.git.patch files) - Git-compatible format
• Multifile patches - Combined patches for multiple files
• Patch bundles - Organized directory structure with manifest

Examples

Development Workflow

# Watch Rust project files only
watchdiff-tui --extensions rs,toml,md

# Watch with additional ignores
watchdiff-tui --ignore "*.log,tmp/*"

# JSON output piped to file
watchdiff-tui --output json > changes.log

CI/CD Integration

# Compact format for build scripts  
watchdiff-tui --output compact --no-color

# Export patches for review process
watchdiff-tui --algorithm patience --export-dir ./review-patches

Programmatic Usage

WatchDiff can also be used as a Rust library with a powerful API:

use watchdiff_tui::{
    diff::{DiffGenerator, DiffAlgorithmType, DiffFormatter},
    export::DiffExporter,
};

// Generate diffs with different algorithms
let generator = DiffGenerator::new(DiffAlgorithmType::Patience);
let result = generator.generate(old_content, new_content);

// Format as unified diff
let formatted = DiffFormatter::format_unified(&result, "old.rs", "new.rs");

// Export to file
let exporter = DiffExporter::unified();
exporter.export_diff(&result, old_path, new_path, "changes.patch")?;

// Get statistics
println!("Changes: {} additions, {} deletions", 
    result.stats.lines_added, 
    result.stats.lines_removed
);

Library Features

• Trait-based architecture for extensible diff algorithms
• Multiple export formats (unified, Git patch, side-by-side)
• Rich diff statistics and metadata
• Professional patch management capabilities
• Comprehensive test coverage

See examples/advanced_usage.rs for complete usage examples.

Architecture

WatchDiff is built with modern Rust practices and clean architecture:

Module Organization

src/
├── core/           # Core file watching and event handling
│   ├── events.rs   # Event definitions and processing
│   ├── filter.rs   # File filtering with .gitignore support
│   └── watcher.rs  # File system monitoring
├── diff/           # Modular diff generation system
│   ├── algorithms.rs  # Trait-based algorithm implementations
│   ├── generator.rs   # High-level diff generation
│   └── formatter.rs   # Multiple output formats
├── export/         # Professional patch export capabilities
├── ui/             # Terminal user interface
└── highlight.rs    # Syntax highlighting integration

Key Dependencies

• File Watching: notify crate for cross-platform filesystem events
• TUI: ratatui with crossterm for beautiful terminal interfaces
• Syntax Highlighting: syntect crate for 25+ programming languages
• CLI: clap for robust argument parsing with derive macros
• Diffing: similar crate with multiple algorithm implementations
• Filtering: ignore crate for comprehensive .gitignore support
• Async: tokio for non-blocking operations
• Date/Time: chrono for export timestamps and metadata

Design Principles

• Trait-based Design: Extensible algorithms via traits
• Separation of Concerns: Clear module boundaries
• Type Safety: Comprehensive type system usage
• Performance: Zero-cost abstractions and efficient algorithms
• Testability: Each module independently testable with comprehensive coverage

Performance

• Handles thousands of files efficiently
• Memory-bounded event history (configurable)
• Native filesystem events (with polling fallback)
• Optimized diff generation
• Background processing threads

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please open issues or pull requests.