Crate wlk

Crate wlk 

Source
Expand description

§WLK - File-Centric Version Control System

WLK (Walkabout) is a file-centric, event-sourced version control system with implicit branching. Unlike traditional VCS that track repository-level snapshots, WLK tracks each file independently with its own complete delta history.

§Key Features

  • File-Centric Architecture: Each file has its own shadow file containing complete history
  • Implicit Branching: Rewind to any point and edit - a new branch is created automatically
  • Event-Sourced: All changes are stored as a sequence of delta operations
  • Per-File Branching: Each file can have multiple parallel histories independently
  • Crash-Safe: Write-ahead log ensures atomic operations
  • Human-Readable: Shadow files are JSON for easy inspection

§Quick Example

use wlk::{Repository, DeltaOperation, ShadowFile};
use std::fs;
use std::path::Path;

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

// Create and track a file
fs::write("example.txt", "Hello, World!")?;
repo.track_file(Path::new("example.txt"))?;

// Make changes
fs::write("example.txt", "Hello, WLK!")?;

// Create snapshot
let shadow_path = ShadowFile::shadow_path(Path::new("example.txt"))?;
let mut shadow = ShadowFile::load(&shadow_path)?;
let content = fs::read_to_string("example.txt")?;
shadow.apply_delta(
    DeltaOperation::Snapshot { content },
    Some("Updated greeting".to_string()),
)?;
shadow.save(&shadow_path)?;

// View history
let history = shadow.get_history();
println!("Total versions: {}", history.len());

§Architecture

§Shadow Files

Each tracked file foo.rs has a corresponding shadow file .wlk/foo.rs.wlk that stores:

  • Initial snapshot
  • All delta operations (Insert, Delete, Replace, Snapshot)
  • Parent-child relationships forming a delta tree
  • Current HEAD pointer

§Delta Operations

  • Insert: Add text at position
  • Delete: Remove text from range
  • Replace: Replace range with new text
  • Snapshot: Create full checkpoint

§Implicit Branching

d0 (initial)
├─ d-abc (feature A)
│  └─ d-def (refined A)
└─ d-xyz (feature B)  ← Just rewind and edit!

§Modules

  • delta: Delta operation definitions and application
  • shadow: Shadow file management and delta tree
  • repository: Repository initialization and file tracking
  • config: Configuration management
  • diff: Text diffing utilities
  • utils: Helper functions

Re-exports§

pub use config::Config;
pub use delta::Delta;
pub use delta::DeltaId;
pub use delta::DeltaOperation;
pub use metalog::MetaEvent;
pub use metalog::MetaLog;
pub use metalog::MetaLogEntry;
pub use repository::FileStatus;
pub use repository::FileStatusInfo;
pub use repository::Repository;
pub use shadow::ShadowFile;

Modules§

config
delta
diff
metalog
repository
shadow
utils
wal