KitCat VCS

KitCat is a Git-like version control system implemented in Rust, designed to be simple, fast, and Git-compatible where possible. It's an educational project demonstrating how version control systems work under the hood.

✨ Features

✅ Currently Implemented

• Repository Management

  • Initialize repositories (.kitcat directory structure)
  • Configuration management (user.name, user.email)

• Object Storage

  • Content-addressable blob storage with SHA-1 hashing
  • Zlib compression for efficient storage
  • Tree objects for directory snapshots
  • Commit objects with full metadata (author, timestamp, parents)

• Staging Area

  • Binary DIRC format index (Git-compatible)
  • File metadata tracking (permissions, timestamps)
  • Atomic writes with file locking

• Version Control

  • Create commits with messages
  • View commit history (log, log --oneline)
  • Branch management (create, list, delete, switch)
  • Checkout (branch switching, detached HEAD, file restoration)
  • Working tree status (staged, unstaged, untracked files)
  • Diff (compare working tree, index, and commits)
  • Merge (three-way merge with conflict detection and resolution)
  • Show commit details

• CLI Interface

  • Full command-line interface with help
  • Intuitive Git-like commands

• Repository Optimization

  • Garbage collection with object packing
  • Packfile format for efficient storage
  • Prune unreachable objects
  • Repository size optimization

📋 Planned

• Delta compression for packfiles
• LFS (Large File Storage) for very large files
• Remote repository support
• Network operations (push, pull, fetch)
• Advanced merge strategies
• Submodules

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/kitcat.git
cd kitcat

# Build in release mode
cargo build --release

# The binary is at target/release/kitcat
# Optionally, add to your PATH

See the Installation Guide for detailed instructions.

Your First Repository

# Initialize a new repository
kitcat init

# Configure your identity
kitcat config user.name "Your Name"
kitcat config user.email "you@example.com"

# Create and add a file
echo "# My Project" > README.md
kitcat add README.md

# Create your first commit
kitcat commit -m "Initial commit"

# View history
kitcat log

See the Quick Start Guide for a complete tutorial.

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started

  • Installation Guide
  • Quick Start (5 minutes)
  • Command Reference

• Guides

  • Testing Guide - How to test KitCat
  • Architecture - System design and internals

🛠️ Development

Prerequisites

• Rust 1.92.0 or later
• Cargo (comes with Rust)

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- init

Testing

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

# Run manual tests
./test-kitcat.sh  # See docs/testing-guide.md

📖 Usage Examples

Basic Workflow

# Initialize repository
kitcat init

# Configure identity
kitcat config user.name "Developer"
kitcat config user.email "dev@example.com"

# Add files
kitcat add file1.txt
kitcat add file2.txt

# Create commit
kitcat commit -m "Add initial files"

# View history
kitcat log --oneline

Working with Branches

# Create a branch
kitcat branch feature-x

# List branches
kitcat branch

# Switch to branch
kitcat branch feature-x

# Make changes and commit
kitcat add newfile.txt
kitcat commit -m "Add feature"

# Switch back to master
kitcat branch master

# Delete branch
kitcat branch -d feature-x

Merging Branches

# Create and switch to a feature branch
kitcat branch feature
kitcat checkout feature

# Make changes on feature branch
echo "new feature" > feature.txt
kitcat add feature.txt
kitcat commit -m "Add new feature"

# Switch back to master
kitcat checkout master

# Merge feature into master
kitcat merge feature

# If there are conflicts:
# - Edit files to resolve conflicts
# - Stage the resolved files
kitcat add resolved-file.txt
# - Continue the merge
kitcat merge --continue

# Or abort the merge
kitcat merge --abort

Inspecting Objects

# Write tree from index
kitcat write-tree

# List tree contents
kitcat list-tree <tree-hash>

# Show commit details
kitcat show-commit <commit-hash>

# View commit history
kitcat log
kitcat log --oneline
kitcat log -n 5

🏗️ Architecture

KitCat uses a modular architecture:

┌─────────────────────────────────────┐
│           CLI Layer                 │
│      (Command Parsing)              │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│        Commands Layer               │
│   (Business Logic)                  │
└────┬───────┬────────┬───────────────┘
     │       │        │
┌────▼───┐ ┌─▼────┐ ┌▼────────┐
│ Index  │ │Object│ │  Repo   │
│ (Stage)│ │Storage│ │ (Config)│
└────────┘ └──────┘ └─────────┘

Object Model: Git-compatible

• Blobs: File content
• Trees: Directory snapshots
• Commits: Versioned snapshots with metadata

Storage: Content-addressable

• SHA-1 hashing for deduplication
• Zlib compression
• Split directories for performance

See Architecture Documentation for details.

🎯 Project Goals

1. Educational: Demonstrate how VCS internals work
2. Git-Compatible: Use same object formats as Git
3. Performance: Leverage Rust's zero-cost abstractions
4. Simplicity: Clean, readable codebase
5. Extensible: Easy to add new features

📊 Project Status

Version: 0.1.0 (Alpha) Rust Edition: 2024

Feature Completeness

Feature	Status
Repository initialization	✅ Complete
Binary index (staging)	✅ Complete
Blob objects	✅ Complete
Tree objects	✅ Complete
Commit objects	✅ Complete
Branch management	✅ Complete
Commit history (log)	✅ Complete
Configuration	✅ Complete
Status command	✅ Complete
Checkout	✅ Complete
Diff	✅ Complete
Merge	✅ Complete
Garbage collection	✅ Complete
Packfiles	✅ Complete

Phase 1 Progress: 11/11 features complete (100%) ✨

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide (coming soon) for details on our code of conduct and the process for submitting pull requests.

Areas Where We Need Help

• Large file support (packfiles, delta compression, LFS)
• Test coverage expansion
• Performance optimization
• Documentation improvements
• Remote repository support

📜 License

This project is licensed under the MIT License - see the LICENSE.rst file for details.

🙏 Acknowledgments

• Inspired by Git and its excellent internals documentation
• Built with Rust 🦀
• Uses clap for CLI parsing
• Compression with flate2

📞 Support & Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

🔗 Related Projects

• Git - The inspiration
• libgit2 - Git implementation library
• gitoxide - Git implementation in Rust
• jujutsu - Version control tool in Rust

---

Built with ❤️ and Rust 🦀

KitCat: Because version control should be easy to understand!