GIT - A Complete Python Implementation

A simple Python implementation of Git to understand how version control works under the hood.

---

What is This Project?

This project is a simplified Git clone written in Python. It implements the fundamental operations of Git:

• Object Storage - How Git stores files, directories, and commits
• Staging Area - How git add prepares files for commit
• Commits - How Git creates snapshots of your project
• Branches - How Git manages different lines of development
• Merging - How Git combines branches together
• And more!

By studying this code, you'll understand:

• Why Git uses SHA-1 hashes
• How Git compresses and stores data
• What happens when you run git add, git commit, etc.
• How branches are just pointers to commits

---

Features Implemented

Command	Description
init	Initialize a new repository
add	Stage files for commit
commit	Create a new commit
status	Show repository status
log	View commit history
branch	List, create, or delete branches
checkout	Switch branches or checkout commits
merge	Merge branches together
cherry-pick	Apply a specific commit
stash	Temporarily save changes

---

Project Structure

git-impl/
│
├── main.py              # Entry point - connects CLI to Repository
├── cli.py               # Command-line argument parsing
├── repository.py        # Main Repository class with all Git operations
│
├── objects/             # Git object types
│   ├── __init__.py      # Package exports
│   ├── base.py          # GitObject - base class (hashing, serialization)
│   ├── blob.py          # Blob - stores file contents
│   ├── tree.py          # Tree - stores directory structure
│   └── commit.py        # Commit - stores commit metadata
│
├── README.md            # This file
└── tech_doc.md          # Technical documentation with examples

---

Data Structures

1. GitObject (Base Class)

The foundation for all Git objects. Handles:

• SHA-1 hash generation
• Zlib compression/decompression
• Serialization to/from bytes

2. Blob (Binary Large Object)

• Stores the raw contents of a file
• Does NOT store the filename (that's in the Tree)
• Format: blob <size>\0<content>

3. Tree

• Represents a directory
• Contains list of entries: (mode, name, hash)
• Each entry points to a Blob (file) or another Tree (subdirectory)
• Format: tree <size>\0<mode> <name>\0<20-byte-hash>...

4. Commit

• Represents a snapshot of the project
• Contains:
  • tree - hash of root Tree
  • parent - hash of previous commit(s)
  • author - who wrote the code
  • committer - who made the commit
  • message - description of changes
  • timestamp - when it was created

5. Repository

• Manages the .git directory
• Handles all Git operations
• Stores objects in .git/objects/
• Tracks branches in .git/refs/heads/

---

Installation & Quick Start

Prerequisites

• Python 3.7 or higher
• No external dependencies (uses only standard library)

Getting Started

# Clone this repository
git clone <repo-url>
cd git-impl

# Initialize a new PyGit repository
python main.py init

# Create a file and stage it
echo "Hello World" > hello.txt
python main.py add hello.txt

# Create your first commit
python main.py commit -m "Initial commit"

# Check status
python main.py status

# View history
python main.py log

---

Usage Examples

Basic Workflow

# Initialize repository
python main.py init

# Add files
python main.py add file.py
python main.py add src/           # Add entire directory

# Commit changes
python main.py commit -m "Add new feature"

# Check status
python main.py status

Branch Operations

# List all branches
python main.py branch

# Create new branch
python main.py branch feature

# Switch to branch
python main.py checkout feature

# Create and switch in one command
python main.py checkout -b new-feature

# Delete branch
python main.py branch -d old-branch

Advanced Operations

# Merge a branch
python main.py merge feature

# Cherry-pick a commit
python main.py cherry-pick abc1234

# Stash changes
python main.py stash push -m "Work in progress"
python main.py stash list
python main.py stash pop

# Checkout specific commit (detached HEAD)
python main.py checkout abc1234def5678...

---

How Git Stores Data

.git/
├── objects/           # All objects stored here
│   ├── ab/           # First 2 chars of hash
│   │   └── cdef...   # Remaining 38 chars
│   └── ...
├── refs/
│   └── heads/        # Branch pointers
│       ├── master    # Contains commit hash
│       └── feature   # Contains commit hash
├── HEAD              # Points to current branch
├── index             # Staging area (JSON format)
└── stash             # Stashed changes

---

Learn More

For detailed technical documentation with flowcharts and examples, see tech_doc.md.

---

Special Thanks

A huge thank you to Rivaan Ranawat for the excellent tutorial that inspired and guided this project!

Watch the full 5-hour tutorial:
I Built My Own Git From Scratch (And Here's How You Can) | Git Tutorial

This tutorial provides a clear, step-by-step explanation of Git internals and how to implement them in Python. Highly recommended for anyone wanting to understand how Git really works!