WLK - File-Centric Version Control

WLK (Walkabout) is a file-centric, event-sourced version control system with implicit branching. Unlike Git which tracks repository-level snapshots, WLK gives each file its own complete delta history.

Why WLK?

• 🎯 File-First: Each file has its own independent history
• 🌳 Implicit Branching: Just rewind and edit - new branch created automatically
• 🔍 Human-Readable: Shadow files are JSON, inspect with any editor
• ⚡ Simple: No staging area, no index, no repository-level complexity
• 🛡️ Crash-Safe: Write-ahead log ensures atomic operations

Quick Start

Install

cargo install wlk

Basic Usage

# Initialize tracking
wlk init

# Track a file
echo "Hello World" > app.rs
wlk track app.rs

# Make changes
echo "Hello WLK!" > app.rs
wlk snapshot app.rs -m "Updated greeting"

# View history
wlk log app.rs

# See what changed
wlk diff app.rs

# Check status
wlk status

Branching Workflow

# Create initial version
echo "fn main() { v1 }" > app.rs
wlk snapshot app.rs -m "Version 1"

# Try alternative approach
wlk rewind app.rs
echo "fn main() { v2 }" > app.rs
wlk snapshot app.rs -m "Version 2"

# Now you have TWO versions in parallel!
wlk branches app.rs
# Shows:
# d0
# ├─ d-abc (Version 1)
# └─ d-xyz (Version 2) ← HEAD

# Switch between them anytime
wlk show app.rs --delta d-abc  # See Version 1

Key Concepts

File-Centric Design

project/
├── src/
│   ├── .wlk/              # Tracking metadata
│   │   ├── main.rs.wlk    # Complete history of main.rs
│   │   └── lib.rs.wlk     # Complete history of lib.rs
│   ├── main.rs            # Your working file
│   └── lib.rs

Each tracked file has a shadow file containing:

• Initial snapshot
• All changes as delta operations
• Complete delta tree with branches
• Current HEAD pointer

Implicit Branching

No explicit branch or checkout commands. Just:

1. Rewind to any point: wlk rewind app.rs
2. Make changes: echo "new" > app.rs
3. Snapshot: wlk snapshot app.rs

Boom! New branch created automatically.

Delta Tree

d0 (initial)
├─ d-abc (feature A)
│  └─ d-def (refined A)
└─ d-xyz (feature B - alternative)
   └─ d-ghi (B improved)

Every file can have its own branches without affecting other files.

Commands

Core Commands

History & Navigation

Comparison & Time Travel

Configuration

Library Usage

use wlk::{Repository, DeltaOperation, ShadowFile};

// Initialize repository
let mut repo = Repository::init(".")?;

// Track file
repo.track_file("app.rs".as_ref())?;

// Create snapshot
let shadow_path = ShadowFile::shadow_path("app.rs".as_ref())?;
let mut shadow = ShadowFile::load(&shadow_path)?;
shadow.apply_delta(
    DeltaOperation::Snapshot {
        content: "new content".to_string()
    },
    Some("my change".to_string()),
)?;
shadow.save(&shadow_path)?;

// View history
for delta in shadow.get_history() {
    println!("{}: {:?}", delta.id, delta.annotation);
}

See examples/ for more.

Comparison with Git

WLK is NOT a Git replacement. It's for:

• Personal projects where you want fine-grained control
• Experimentation with multiple approaches
• Learning about version control internals
• Projects where per-file history makes sense

Roadmap

• ✅ v0.1 - Core functionality, CLI, basic features
• 🔄 v0.2 - Automatic file watching, faster operations
• 📋 v0.3 - Merge/conflict resolution
• 📋 v0.4 - TUI interface
• 📋 v1.0 - Production ready, binary format

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

Dual-licensed under MIT or Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Credits

Built by Rikii. Inspired by Git, Fossil, and event sourcing principles.