GitDB: SQL-Backed Version Control

GitDB is a standalone command-line version control system that replicates the core functionality of Git, but replaces the traditional flat-file object store with a relational SQLite database.

By storing version history in relational tables, every commit, branch, tree, and blob becomes fully queryable using standard SQL. This unlocks powerful analytics, simplified repository traversal, and native deduplication.

Features

• Familiar CLI: Provides standard commands like init, add, commit, log, branch, and checkout.
• Relational Storage: All data is stored in .gitdb/repo.db, a standard SQLite database.
• Native Deduplication: File contents (blobs) are hashed via SHA-256 and stored efficiently.
• Atomic Operations: Commits are wrapped in strict database transactions ensuring consistent state.
• Extensive Test Coverage: Backed by a robust suite of unit tests.

Installation

GitDB is built with Python 3 and uses the standard library for all core logic. The only external dependency is pytest for running the test suite.

# Clone the repository
git clone https://github.com/eko-071/gitdb.git
cd gitdb

# Create a virtual environment and install test dependencies (optional)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

Use the gitdb.py entrypoint to interact with your repositories.

Command	Description
python gitdb.py init	Initialize a new GitDB repository in the current directory
python gitdb.py add <file>	Stage a file for the next commit
python gitdb.py commit -m 'msg'	Create a commit from all staged files
python gitdb.py log	Show the commit history of the current branch
python gitdb.py branch <name>	Create a new branch at the current commit
python gitdb.py branch --list	List all branches, marking the current one with *
python gitdb.py checkout <branch>	Switch HEAD to a different branch

Architecture & Schema

GitDB's architecture is divided into three layers:

1. CLI Layer (src/cli.py, gitdb.py): Parses commands and provides output formatting.
2. Core Logic Layer (src/core.py): Handles SHA-256 hashing, tree constructions, and validation.
3. Database Layer (src/db.py): Executes raw parameterised SQL queries and handles transactions.

Database Schema

The database uses 7 tables to represent the repository state:

• blobs: Stores raw file content deduplicated by its SHA-256 hash.
• trees & tree_entries: Represents the directory structure for a specific commit.
• commits: Links a root tree, an author, a timestamp, a message, and a parent commit.
• refs & HEAD: Tracks branches and the active working branch.
• staging_area: Temporarily holds files before they are committed.

Testing and Demonstration

Running the Test Suite

GitDB is fully tested using pytest. The suite covers all core algorithms, database interactions, and CLI outputs.

pytest tests/

Running the SQL Demo

To see the power of relational version control in action, use the included demo scripts:

1. Seed a mock repository:

   python seed_demo.py

   This generates a demo_repo/ directory populated with several commits, branches, and deduplicated files.

2. Run the demo SQL queries:

   sqlite3 demo_repo/.gitdb/repo.db < demo_queries.sql

   This script runs 8 complex queries directly against the repository's history, demonstrating tasks like counting commits per author, tracing files across history, and analyzing deduplication efficiency.