RevTool: A Modern Version Control System

RevTool is a lightweight, approachable version control system implemented from scratch in Rust. It focuses on simplicity, performance, and modern content-addressable storage principles while providing a familiar workflow for developers used to Git.

The project aims to deliver a more understandable and transparent approach to version control, making it both a practical tool and an educational resource for understanding how version control systems work.

Why RevTool?

• Simplicity: Clear conceptual model with straightforward commands
• Modern design: Built using Rust and BLAKE3 cryptographic hashing
• Approachable code: Well-organized architecture for learning and extending
• Interactive workflows: Guided operations for complex tasks like merges
• Familiar feel: Git-like concepts with more intuitive naming and behavior

Table of Contents

• Quick Start
• Key Differences from Git
• Installation
• Feature Highlights
• Command Reference
• Common Workflows
• Advanced Features
• Architecture
• Troubleshooting
• Contributing
• License

Quick Start

Get up and running with RevTool in minutes:

# Install RevTool
git clone https://github.com/SamuelSchlesinger/version-control.git
cd version-control
cargo build --release
export PATH="$PATH:$(pwd)/target/release"  # Add to your path

# Start your project
mkdir my-project
cd my-project
revtool init
echo "# My Project" > README.md
revtool status
revtool snap -m "Initial commit"

# Create and use a feature branch
revtool branch feature
revtool checkout feature
# Make changes...
revtool status
revtool snap -m "Add new functionality"

# Merge changes back to main branch
revtool checkout dev
revtool merge feature -m "Merge feature branch"

Key Differences from Git

RevTool builds on Git's concepts while simplifying and modernizing several aspects:

While Git offers more advanced features and widespread adoption, RevTool provides a cleaner, more approachable design that's ideal for:

• Learning how version control works
• Personal projects where simplicity is valued
• Educational environments
• Projects that benefit from interactive merge resolution

Installation

From Source

Clone the repository and build with Cargo:

git clone https://github.com/SamuelSchlesinger/version-control.git
cd version-control
cargo build --release

The binary will be available at target/release/revtool.

For convenience, you can add it to your PATH:

# Temporary (current session only)
export PATH="$PATH:$(pwd)/target/release"

# Permanent (add to your .bashrc, .zshrc, etc.)
echo 'export PATH="$PATH:/path/to/version-control/target/release"' >> ~/.bashrc
source ~/.bashrc

Prerequisites

• Rust (1.54 or later recommended)
• Cargo

Verifying Installation

To verify the installation:

revtool --version

Feature Highlights

RevTool offers a range of powerful features designed for modern version control workflows:

Core Features

• Content-addressable storage with BLAKE3 cryptographic hashing

  • Efficient storage with automatic deduplication
  • Cryptographic verification of content integrity
  • Fast object retrieval

• Branch-based workflow with intuitive semantics

  • Simple branch creation and switching
  • Support for multiple development lines
  • Familiar mental model for Git users

• Snapshot-based versioning with complete history

  • Directed acyclic graph (DAG) for history tracking
  • Support for merge commits with multiple parents
  • Efficient storage that only tracks changes

• Flexible file ignoring with gitignore-compatible patterns

  • Use familiar glob syntax
  • Automatically ignore common build artifacts
  • Interactive pattern management

• Comprehensive diffing capabilities

  • Structural diffs (files added/removed/modified)
  • Content-level diffs (line-by-line changes)
  • Rich formatting with context

Advanced Features

• Robust merge capabilities

  • Three-way merging with conflict detection
  • Interactive conflict resolution
  • Multiple automatic merge strategies
  • Custom editor support for conflict resolution

• Flexible snapshot references

  • Support for branch names, direct IDs
  • Relative references like HEAD~N
  • Shortened hash prefixes

• Interactive mode for guided operations

  • Simplified workflows for complex tasks
  • Clear conflict resolution interfaces
  • Friendly confirmation prompts

Command Reference

Usage: revtool [OPTIONS] <COMMAND>

Commands:
  usage     Display help information and usage examples
  ignore    Manage the ignore patterns
  init      Initialize a brand new revision control repository
  diff      Check the difference between snapshots
  changes   Shows files and directories changed since the latest snapshot
  status    Show working tree status
  snap      Take a new snapshot (similar to git commit)
  merge     Merge changes from another branch into the current branch
  checkout  Switch to a branch
  branch    Create or list branches
  reset     Reset all files to the last snapshot on this branch
  log       Show commit logs
  help      Print this message or the help of the given subcommand(s)

Options:
  -i, --interactive  Use interactive mode with prompts and confirmations
  -h, --help         Print help
  -V, --version      Print version

Key Commands

Initialize a Repository

revtool init

Creates a new .rev directory to track your files.

Checking Status

revtool status
revtool status --content  # Shows content-level changes

Shows which files have been added, modified, or deleted.

Taking Snapshots (Committing)

revtool snap -m "Your commit message"
revtool snap -i  # Interactive mode with guided prompts

Records the current state of your files.

Branch Management

revtool branch                 # List branches
revtool branch feature-name    # Create a new branch
revtool checkout feature-name  # Switch to a branch

Comparing Versions

revtool diff main feature      # Compare two branches
revtool diff HEAD~1            # Compare with previous snapshot
revtool diff --content main    # Show content-level differences

Viewing History

revtool log         # Show recent snapshots
revtool log -l 5    # Show 5 most recent snapshots

Ignoring Files

revtool ignore                # List current patterns
revtool ignore "*.log"        # Add a pattern
revtool ignore --remove "*.log"  # Remove a pattern
revtool ignore -i             # Interactive pattern management

Resetting Files

revtool reset                 # Reset to last snapshot
revtool reset --delete-absent # Reset and delete untracked files

Common Workflows

Starting a New Project

# Initialize a repository
revtool init

# Create initial files
echo "# My Project" > README.md

# Check status
revtool status

# Create first snapshot
revtool snap -m "Initial commit"

Making Changes

# Edit files...

# Check what's changed
revtool status
revtool status --content  # See the actual content changes

# Record the changes
revtool snap -m "Add feature X"

Working with Branches

# Create and switch to a feature branch
revtool branch new-feature
revtool checkout new-feature

# Make changes and commit them
# ... edit files ...
revtool snap -m "Work on new feature"

# Compare with main branch
revtool diff main

# Switch back to main
revtool checkout main

Merging Branches

# Work on feature branch
revtool checkout feature-branch
# ... make changes and create snapshots ...

# Switch to target branch and merge
revtool checkout main
revtool merge feature-branch -m "Merge feature-branch into main"

# If there are conflicts, you'll be prompted to resolve them
# After resolving conflicts manually
revtool merge --continue

# If you want to abort a merge with conflicts
revtool merge --abort

Advanced Features

Merge Strategies

RevTool provides several advanced merge capabilities to handle different scenarios:

# Automatically resolve all conflicts by taking our (current branch) version
revtool merge feature-branch --strategy ours

# Automatically resolve all conflicts by taking their (merging branch) version
revtool merge feature-branch --strategy theirs

# Default behavior, requires manual resolution
revtool merge feature-branch --strategy normal

In interactive mode (-i), even with a strategy specified, you'll still be shown the conflicts that were automatically resolved.

Custom Editor for Conflict Resolution

Specify your preferred editor for resolving merge conflicts:

# Use vim to edit conflict files
revtool merge feature-branch --editor vim

# Use VS Code to edit conflict files
revtool merge feature-branch --editor "code -w"

The editor will be launched automatically when you choose to manually edit a conflict.

Interactive Mode

Most commands support an interactive mode with -i that guides you through the process:

revtool snap -i       # Interactive snapshot creation
revtool checkout -i   # Interactive branch selection
revtool ignore -i     # Interactive ignore management

Architecture

RevTool follows a design philosophy centered on simplicity, understandability, and functional purity. Core principles include:

• Content-addressable storage as the foundation
• Immutable objects for reliability
• Clean separation of concerns in modular components
• Type safety through Rust's strong typing system
• Explicit over implicit in operations and commands

Core Components

1. ObjectId (object_id.rs)

   • Unique identifier based on content hash (BLAKE3)
   • Used to address all content in the system

2. ObjectStore (object_store.rs)

   • Content-addressable storage interface
   • Provides filesystem (DirectoryObjectStore) and in-memory implementations
   • Automatically deduplicates identical content

3. Directory (directory.rs)

   • Represents a directory tree structure
   • Maps file paths to their content hashes
   • Includes diffing capabilities for comparing directories

4. SnapShot (snapshot.rs)

   • Represents a point-in-time version of the repository
   • Links to a directory structure and parent snapshot(s)
   • Forms nodes in the version history graph

5. DotRev (dot_rev.rs)

   • Manages the .rev directory structure
   • Provides repository metadata operations
   • Handles branch management

6. Content Diffing (content_diff.rs)

   • Implements line-based diffing for text files
   • Uses a simplified Myers diff algorithm

7. Snapshot References (snapshot_ref.rs)

   • Flexible syntax for referencing snapshots
   • Supports branch names, HEAD, relative refs (HEAD~1), and direct IDs

Repository Structure

The .rev directory contains:

.rev/
  ├── store/         # Content-addressable object store
  │   └── xx/        # Two-digit prefix subdirectories for efficient lookup
  │       └── yy...  # Object contents stored by remaining hash digits
  ├── branches/      # Branch references
  │   ├── main       # Each file contains a snapshot ID
  │   └── dev        # ...for the tip of the branch
  ├── branch         # Text file containing current branch name
  └── ignores        # JSON file with patterns for ignored files

All objects (files, directories, snapshots) are stored in the content-addressable store and referenced by their hash, ensuring integrity and deduplication.

Troubleshooting

Common Issues

Issue: "Repository not initialized" error Solution: Run revtool init in the root directory of your project.

Issue: Changes not showing up in status Solution: Check if the files are in the ignore list with revtool ignore. Files matching ignore patterns won't appear in status.

Issue: Failed merge with conflicts Solution:

1. Resolve conflicts in the marked files
2. Run revtool merge --continue
3. If you want to start over, use revtool merge --abort

Issue: "Branch not found" error Solution: List available branches with revtool branch and check spelling. If needed, create the branch first.

Debugging Tips

• Use revtool status --content for detailed change information
• Examine the .rev directory structure for troubleshooting repository issues
• Try interactive mode (-i) for complex operations to see more information

Getting Help

• Use revtool usage <command> for detailed help on a specific command
• Review this README for workflow guidance
• Submit issues via GitHub for bugs or feature requests

Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Create a new branch for your feature or fix
3. Make your changes
4. Submit a pull request

Please ensure your code follows the existing style patterns and includes appropriate tests.

Development Workflow

1. Clone your fork: git clone https://github.com/your-username/version-control.git
2. Add upstream: git remote add upstream https://github.com/SamuelSchlesinger/version-control.git
3. Create branch: git checkout -b my-feature
4. Make changes and test
5. Commit: git commit -am "Add new feature"
6. Push: git push origin my-feature
7. Create PR through GitHub

License

See the LICENSE file for details.