# WLK Quick Start Guide
Get started with WLK in 5 minutes.
## Installation
```bash
# From source
git clone <repository>
cd wlk
cargo build --release
# Add to PATH (optional)
sudo cp target/release/wlk /usr/local/bin/
```
## Your First Repository
```bash
# Create a new project
mkdir my-project
cd my-project
# Initialize WLK
wlk init
# This creates:
# .wlk/
# ├── config # Repository configuration
# ├── metalog # Root directory events
# └── wal # Write-ahead log (temporary)
```
## Track Your First File
```bash
# Create a file
echo "fn main() {}" > main.rs
# Start tracking
wlk track main.rs
# This creates a shadow file:
# .wlk/main.rs.wlk # Contains complete history
```
## Make Changes
```bash
# Edit the file
echo "fn main() { println!(\"Hello\"); }" > main.rs
# Create a snapshot
wlk snapshot main.rs -m "Added hello message"
# View history
wlk history main.rs
```
Output:
```
[2025-11-10 10:00:00] d0: Snapshot (13 bytes) - Initial snapshot
[2025-11-10 10:05:00] d-abc123: Snapshot (35 bytes) - Added hello message
Current HEAD: d-abc123
```
## Navigate History
```bash
# Go back one change
wlk rewind main.rs
# File is now reverted to: fn main() {}
# See current content
cat main.rs
# Output: fn main() {}
# View where you are
wlk history main.rs --tree
```
## Create Branches
```bash
# After rewinding, make a different change
echo "fn main() { println!(\"Different\"); }" > main.rs
# Snapshot creates a new branch
wlk snapshot main.rs -m "Alternative approach"
# View branch structure
wlk branches main.rs
```
Output:
```
Branch points:
d0 (2 branches)
→ d-abc123
→ d-def456
Leaf nodes (current branches):
d-abc123
d-def456 (HEAD)
```
## Common Commands
### List tracked files
```bash
wlk list
```
### View file at specific delta
```bash
wlk show main.rs --delta d-abc123
```
### View history as tree
```bash
wlk history main.rs --tree
```
### Stop tracking a file
```bash
wlk untrack main.rs
```
## Understanding the Structure
### Working Directory
```
my-project/
├── main.rs # Your working file (this is HEAD)
├── lib.rs # Another file
└── .wlk/ # Version control metadata
├── main.rs.wlk # Shadow file for main.rs
├── lib.rs.wlk # Shadow file for lib.rs
├── metalog # Directory events
├── config # Repository config
└── wal # (temporary)
```
### Shadow File Contents (.wlk/main.rs.wlk)
```json
{
"file": "main.rs",
"initial_snapshot": {
"id": "d0",
"timestamp": "2025-11-10T10:00:00Z",
"operation": { "type": "Snapshot", "content": "..." }
},
"deltas": [
{
"id": "d-uuid-123",
"parent": "d0",
"operation": { "type": "Insert", "index": 10, "value": "..." }
}
],
"current_head": "d-uuid-123"
}
```
## Key Concepts
### 1. Shadow Files
Every tracked file has a shadow file that stores its complete history.
### 2. Deltas
Changes are stored as operations:
- **Insert**: Add text at position
- **Delete**: Remove text range
- **Replace**: Replace text range
- **Snapshot**: Full file content
### 3. Delta Tree
Deltas form a tree via parent references. Branches occur naturally when you rewind and make new changes.
### 4. HEAD
The current delta - which version of the file you're looking at.
## Example Workflow
```bash
# Day 1: Start project
wlk init
echo "// TODO: implement" > feature.rs
wlk track feature.rs
# Day 2: Implement feature
vim feature.rs
wlk snapshot feature.rs -m "Initial implementation"
# Day 3: Realize you want to try different approach
wlk rewind feature.rs
vim feature.rs # Try alternative
wlk snapshot feature.rs -m "Alternative design"
# Day 4: Compare both approaches
wlk branches feature.rs
# View first approach
wlk show feature.rs --delta <first-delta-id>
# View alternative
wlk show feature.rs # (current HEAD)
# Can switch between them anytime
```
## Tips
### 1. Frequent Snapshots
Create snapshots at logical points:
```bash
wlk snapshot file.rs -m "Before refactoring"
# ... make changes ...
wlk snapshot file.rs -m "After refactoring"
```
### 2. Descriptive Messages
Use clear annotations:
```bash
# Good
wlk snapshot main.rs -m "Fixed null pointer bug"
# Less helpful
wlk snapshot main.rs -m "Changes"
```
### 3. Explore Branches
Don't be afraid to create branches - they're cheap:
```bash
wlk rewind file.rs
# Try experimental idea
wlk snapshot file.rs -m "Experimental approach"
# Can always go back to other branch
```
### 4. View Tree Often
Visualize your history:
```bash
wlk history file.rs --tree
```
## Troubleshooting
### "Not in a wlk repository"
```bash
# Make sure you're in a directory with .wlk/
# Or initialize
wlk init
```
### "File is not tracked"
```bash
# Track the file first
wlk track <file>
```
### "Delta not found"
```bash
# List valid deltas
wlk history <file>
```
## What's Different from Git?
| Unit | Commit (repo snapshot) | Delta (file change) |
| Tracking | Repository-wide | Per-file |
| Branches | Explicit refs | Implicit in tree |
| Storage | .git/ database | .wlk/ shadow files |
| Format | Binary objects | JSON (for now) |
## Next Steps
- Read the full [README.md](README.md) for architecture details
- Try the [basic usage example](examples/basic_usage.sh)
- Explore the [branching demo](examples/branching_demo.sh)
- Check out the [test suite](test.sh)
## Getting Help
```bash
# Command help
wlk --help
wlk history --help
# View version
wlk --version
```
## What's Coming Next
- **Milestone 2**: Advanced diff, history search
- **Milestone 3**: File rename tracking, recursive tracking
- **Milestone 4**: Automatic tracking (file watching)
- **Milestone 5**: Merge capabilities
- **Future**: TUI/GUI, distributed sync
---
**You're ready to use WLK!** Start small, experiment with branches, and see how the file-centric model feels for your workflow.