# 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
```bash
cargo install watchdiff-tui
```
### Build from Source
```bash
git clone git@github.com:xicv/watchdiff.git
cd watchdiff
cargo build --release
./target/release/watchdiff
```
## Usage
### Basic Usage
```bash
# 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
```bash
# 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 │
```
#### 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
| `q`, `Esc` | Quit application |
| `h`, `F1` | Toggle help screen |
| `↑`, `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 |
#### 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`)
```bash
$ 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`)
```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`)
```bash
$ 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:
| **Myers** | General purpose | Fast, widely used, good balance |
| **Patience** | Code refactoring | Better handling of moved code blocks |
| **LCS** | Minimal changes | Produces smallest possible diffs |
### 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
```bash
# 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
```bash
# 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:
```rust
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.