# tudiff
[](https://crates.io/crates/tudiff)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org)
[](https://github.com/withoutsalsu/tudiff)
A high-performance terminal directory comparison tool written in Rust - bringing Beyond Compare's intuitive interface to the command line.
π°π· [νκΈ λ¬Έμ](README_KO.md)
## Screenshot
## Features
- **Dual-panel directory trees**: Side-by-side directory comparison for easy visualization
- **Smart color coding**:
- Gray: Identical files/folders
- Red: Files with different content
- Blue: Files/folders on one side only
- **Folder navigation**: Expand or collapse folders with Enter key for quick exploration
- **Synchronized scrolling**: Scroll position and folder expansion automatically synced between panels
- **Fast file comparison**: View file differences instantly with vimdiff
- **Three filter modes**:
- Full view: Display all files and folders
- Difference view: Show only changed items
- Diff only: Show files that exist on both sides but differ
- **Interactive toolbar**: Click toolbar buttons with your mouse
- **Smart file copy**: Copy files while preserving state
- Keeps cursor position and folder expansion after copy
- Preserves file attributes (timestamps, permissions)
- **Safe terminal management**: Restores cursor state even on abnormal exit
## Installation and Usage
### Requirements
- Rust (1.70+)
- vim or nano (for file comparison)
- Terminal with Unicode support (for emoji icons)
### Install from crates.io
```bash
cargo install tudiff
```
### Install from Source
```bash
git clone https://github.com/withoutsalsu/tudiff.git
cd tudiff
# Build only
cargo build --release
# Or install to cargo bin directory
cargo install --path .
```
### Usage
```bash
# For development
cargo run -- <dir1> <dir2>
# If built from source
./target/release/tudiff <dir1> <dir2>
# If installed with cargo install
tudiff <dir1> <dir2>
# Use simple text output instead of TUI (for scripting/piping)
tudiff --simple <dir1> <dir2>
cargo run -- --simple <dir1> <dir2>
# Enable verbose logging (creates tudiff.log file)
tudiff --verbose <dir1> <dir2>
tudiff -v <dir1> <dir2>
cargo run -- --verbose <dir1> <dir2>
```
**Example:**
```bash
# Compare two project directories
tudiff ./project-v1 ./project-v2
# Compare backup with original
tudiff ~/Documents /backup/Documents
# Use simple text output for scripting or piping
# Enable verbose logging for debugging
tudiff --verbose ./project-v1 ./project-v2
```
## Controls
### Mouse Controls
- **Toolbar clicking**: Click on toolbar buttons to activate functions
- **Filter modes**: Click on "All Files", "Different", or "Diff Only" to switch filter modes
- **Actions**: Click on "Expand All", "Collapse All", "Refresh", or "Swap Panels"
- **Mouse wheel**: Scroll up/down to navigate through files
### Keyboard Navigation
- `Up/Down` or `j/k`: Navigate files/folders
- `Left/Right` or `h/l`: Switch between left/right panels
- `Enter`:
- For folders: expand/collapse
- For files: compare with vimdiff (if exists on both sides) or open single file with vim
- `PageUp/PageDown` or `Ctrl+B/Ctrl+F`: Half-page scroll (based on terminal height)
- `Ctrl+Home`: Scroll to top
- `Ctrl+End`: Scroll to bottom
- `1`: Show all files
- `2`: Show only different files
- `3`: Show only different files (no orphans)
- `+`: Expand all folders
- `-`: Collapse all folders
- `F5`: Refresh directories
- `s`: Swap panel contents
- `Ctrl+R` / `Ctrl+L`: Copy selected file (left-to-right / right-to-left)
- `q` or `Esc`: Exit
### Screen Layout
```
βββββββββββ π οΈ Tools βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π All Files(1) β π Different(2) β β‘ Diff Only(3) β π Expand All(+) β
β π Collapse All(-) β π Refresh(F5) β π Swap Panels(s) β βΆοΈCopy(Ctrl+R) β
β Filter: All Files β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββ Left: /path/to/dir1 βββββββββββββββββββββββ Right: /path/to/dir2 ββββββββββ
β π folder1 2.5K Mar 15ββ π folder1 2.5K Mar 15β
β π file1.txt 1.2K Mar 10ββ π file1.txt 1.2K Mar 10β
β π file2.txt 3.4K Mar 12ββ β
β π folder2 5.1K Mar 14ββ π folder2 8.2K Mar 16β
β ββ π subfolder 1.8K Mar 16β
β ββ π newfile.txt 1.8K Mar 16β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
## File Comparison Algorithm
Fast and accurate comparison using step-by-step processing:
1. **Stage 1: File size comparison** (fastest) - Different sizes mean different files
2. **Stage 2: Empty file handling** - 0-byte files are considered identical
3. **Stage 3: Small files** (< 4KB) - Full content comparison
4. **Stage 4: Medium files** (< 1MB) - Fast CRC32 hash comparison
5. **Stage 5: Large files** (β₯ 1MB) - Compare first 4KB only for quick processing
**Note**: This approach provides both speed and accuracy even for large directories.
## UI Enhancements
### User-friendly Interface
- **Mouse support**: Click any toolbar button with your mouse
- **Shortcut hints**: Shortcuts highlighted in red for easy reference (e.g., (1), (2), (3))
- **File information**: File size and modification date shown next to each item
- **Color-coded status**: Different colors for different file states for easy recognition
### Default Sorting
- **Folder-first sorting**: Directories always appear before files
- **Case-insensitive alphabetical**: Files and folders sorted alphabetically ignoring case
## Advanced Features
### Smart Folder Status
Folder colors reflect the status of their contents:
- **Red**: One or more items inside have been changed
- **Blue**: Folder exists on one side only
- **Gray**: All items inside are identical
This helps you quickly find folders with changes.
### Terminal State Management
- **Automatic cursor restoration**: Terminal cursor automatically restored on exit
- **Safe exit**: Terminal state restored even on crashes
- **Cross-platform**: Works on Linux, macOS, and Windows
### Performance Optimizations
- **Background scanning**: Large directories scanned in background with progress display
- **Memory efficient**: Streaming approach saves memory when processing large directories
- **Load on demand**: Tree nodes created only when needed to reduce initial load time
- **Scroll sync**: Both panels scroll together automatically for easy comparison
### Error Handling
- **Smart editor selection**:
- File comparison: vimdiff β vim -d β diff (automatically picks available editor)
- Single file view: vim β vi β nano β cat (adapts to your system)
- **Permission handling**: Skips inaccessible files and continues scanning
- **Network filesystems**: Handles slow or unstable network drives gracefully
- **Minimal requirements**: Works with basic system tools only
## Use Cases
### Development Workflow
```bash
# Compare branches
tudiff ./main-branch ./feature-branch
# Before/after refactoring
tudiff ./before-refactor ./after-refactor
# Compare deployed vs local
tudiff ./local-project /mnt/server/deployed-project
```
### System Administration
```bash
# Configuration drift detection
tudiff /etc/nginx /backup/etc/nginx
# Backup verification
tudiff /home/user /backup/home/user
# System state comparison
tudiff /var/log /backup/var/log
```
### Data Migration
```bash
# Verify file transfers
tudiff /source/data /destination/data
# Compare directory structures
tudiff /old-system/files /new-system/files
```
## Troubleshooting
### Common Issues
**Terminal cursor not blinking after exit:**
- This is automatically handled by tudiff's terminal restoration
- If issues persist, run: `tput cnorm`
**Unicode icons not displaying:**
- Ensure your terminal supports Unicode/UTF-8
- Most modern terminals support this by default
**Performance with very large directories:**
- Use the "Different Only" filter (key `2`) to reduce displayed items
- The tool is optimized for directories with 100K+ files
**Permission errors:**
- The tool will continue scanning and mark inaccessible files appropriately
- Run with appropriate permissions for full access
## Dependencies
Key Rust crates:
- `ratatui`: TUI interface framework
- `crossterm`: Cross-platform terminal manipulation
- `clap`: Command line argument parsing
- `walkdir`: Efficient directory traversal
- `similar`: Text difference algorithms
- `crc32fast`: Fast CRC32 checksum calculation
- `anyhow`: Error handling and context
## License
MIT License
## Similar Tools
**tudiff** vs other directory comparison tools:
- **Beyond Compare**: Commercial, GUI-based, more features but not terminal-native
- **diff -r**: Command line, text output only, no interactive navigation
- **meld**: GUI-based, requires X11/desktop environment
- **kdiff3**: GUI-based, heavy dependency requirements
**tudiff** provides the best of both worlds: powerful comparison features in a lightweight, terminal-native interface.