wlk 0.1.0

# WLK - File-Centric Version Control

[![Crates.io](https://img.shields.io/crates/v/wlk.svg)](https://crates.io/crates/wlk)
[![Documentation](https://docs.rs/wlk/badge.svg)](https://docs.rs/wlk)
[![License](https://img.shields.io/crates/l/wlk.svg)](https://github.com/yourusername/wlk#license)

**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

```bash
cargo install wlk
```

### Basic Usage

```bash
# 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

```bash
# 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

| Command | Description |
|---------|-------------|
| `init` | Initialize WLK tracking |
| `track <file>` | Start tracking a file |
| `untrack <file>` | Stop tracking |
| `snapshot <file> -m "msg"` | Create checkpoint |
| `status` | Show modified/untracked files |
| `list` | List all tracked files |

### History & Navigation

| Command | Description |
|---------|-------------|
| `log <file>` | Show history |
| `log <file> --tree` | Tree view |
| `log <file> --search "text"` | Search by annotation |
| `history <file>` | Alias for log |
| `branches <file>` | Show branch points |
| `show <file>` | Display content at HEAD |
| `show <file> --delta <id>` | Show specific version |

### Comparison & Time Travel

| Command | Description |
|---------|-------------|
| `diff <file>` | Compare working vs HEAD |
| `diff <file> <v1> <v2>` | Compare two versions |
| `diff <file> --stat` | Show statistics |
| `rewind <file>` | Go back one step |
| `rewind <file> -c 3` | Go back 3 steps |

### Configuration

| Command | Description |
|---------|-------------|
| `config set user.name "Name"` | Set user name |
| `config set alias.st "status"` | Create alias |
| `config get <key>` | Get value |
| `config list` | List all settings |
| `completions <shell>` | Generate completions |

## Library Usage

```rust
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/](examples/) for more.

## Comparison with Git

| Feature | WLK | Git |
|---------|-----|-----|
| Granularity | Per-file | Repository |
| Branching | Implicit | Explicit |
| History | Delta tree per file | Commit DAG |
| Storage | JSON shadow files | Binary objects |
| Complexity | Simple | Complex |
| Best For | Experimentation, prototyping | Team collaboration |

**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](CONTRIBUTING.md).

## License

Dual-licensed under MIT or Apache-2.0. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE).

## Credits

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