MVCS - Minimal Version Control System

A minimal version control system implemented in C that demonstrates the core concepts of version control. MVCS supports repository initialization, object storage (blob/tree/commit), SHA-256 hashing, staging area, commits, and history traversal.

Features

• Repository Initialization: Create a new version-controlled repository
• Object Storage: Blob, tree, and commit objects with content-addressable storage
• SHA-256 Hashing: Cryptographic hashing for object identification
• Staging Area: Add files to the index before committing
• Commits: Create snapshots of the repository state
• History: Traverse and display commit history
• Object Inspection: View object contents and metadata

Repository Structure

When you initialize a repository, MVCS creates the following structure:

.mvcs/
├── objects/          # Object database (blobs, trees, commits)
│   └── ab/
│       └── cdef...   # Objects stored by hash (first 2 chars as directory)
├── refs/
│   └── heads/
│       └── master    # Branch references
├── HEAD              # Current branch pointer
└── index             # Staging area

Object Types

Blob

Stores file contents. Each blob is identified by the SHA-256 hash of its content.

Tree

Represents a directory structure, containing entries with:

• File mode (permissions)
• File name
• Hash of the blob or subtree

Commit

Represents a snapshot of the repository, containing:

• Tree hash (root directory)
• Parent commit hash (if not the first commit)
• Author information
• Timestamp
• Commit message

Data Format

Objects are stored with a header format:

<type> <size>\0<content>

Where:

• type is "blob", "tree", or "commit"
• size is the content length in bytes
• \0 is a null terminator
• content is the actual object data

The hash is computed over the entire object (header + content).

Building

Prerequisites

• GCC compiler
• OpenSSL development libraries

On Ubuntu/Debian:

sudo apt-get install build-essential libssl-dev

On macOS:

brew install openssl

Compile

make

This creates the mvcs executable.

Install (optional)

sudo make install

Usage

Initialize a Repository

mvcs init

Creates a .mvcs directory in the current directory.

Add Files to Staging Area

mvcs add <file>

Example:

mvcs add README.md
mvcs add main.c

Create a Commit

mvcs commit "Your commit message"

Example:

export MVCS_AUTHOR="John Doe"
mvcs commit "Initial commit"

View Commit History

mvcs log

Displays all commits in reverse chronological order, showing:

• Commit hash
• Author
• Date and time
• Commit message

Hash a File

mvcs hash-object <file>

Computes and displays the SHA-256 hash of a file as it would be stored in the object database.

Inspect an Object

mvcs cat-file <hash>

Displays the type, size, and contents of an object by its hash.

Example Workflow

# Initialize repository
$ mvcs init
Initialized empty MVCS repository in .mvcs/

# Create a file
$ echo "Hello, MVCS!" > hello.txt

# Add file to staging area
$ mvcs add hello.txt
Added 'hello.txt' to staging area

# Create a commit
$ export MVCS_AUTHOR="Alice"
$ mvcs commit "Add hello.txt"
[a3f2...] Add hello.txt

# Create another file
$ echo "Another file" > test.txt

# Add and commit
$ mvcs add test.txt
Added 'test.txt' to staging area

$ mvcs commit "Add test.txt"
[b7e1...] Add test.txt

# View history
$ mvcs log
commit b7e1...
Author: Alice
Date:   2024-01-01 12:00:00

    Add test.txt

commit a3f2...
Author: Alice
Date:   2024-01-01 11:00:00

    Add hello.txt

Architecture

Core Components

1. repository.c: Repository initialization and validation
2. object.c: Object storage and retrieval, hash computation
3. tree.c: Tree object serialization and parsing
4. commit.c: Commit object creation and reading
5. index.c: Staging area management
6. refs.c: Reference (branch) management
7. commands.c: High-level command implementations
8. main.c: Command-line interface

Design Principles

• Simplicity: Focus on core VCS concepts without complex features
• Correctness: Proper object hashing and storage
• Educational: Clear code structure for learning
• Filesystem-based: All data stored as files for easy inspection
• Content-addressable: Objects identified by their hash

Limitations

This is a minimal implementation designed for educational purposes. It does not include:

• Branching and merging
• Remote repositories
• Compression (zlib)
• Diff/patch functionality
• Directory handling in staging
• File permissions beyond basic mode bits
• Garbage collection
• Pack files
• Submodules or other advanced features

Environment Variables

• MVCS_AUTHOR: Set the author name for commits (default: "Unknown")

License

See LICENSE file for details.

Educational Value

MVCS demonstrates the fundamental concepts of version control systems:

1. Content-addressable storage: Files are stored by their hash
2. Immutable objects: Once created, objects never change
3. DAG structure: Commits form a directed acyclic graph
4. Staging area: Changes are prepared before committing
5. Object types: Different object types for different purposes
6. References: Pointers to commits (branches, HEAD)

This implementation can help understand how systems like Git work internally.