Skip to content

Latest commit

 

History

History
195 lines (145 loc) · 5 KB

README.md

File metadata and controls

195 lines (145 loc) · 5 KB

mini-git-python

A miniature Git command-line interface (CLI) clone written in Python. This project provides insight into Git's core principles including object hashing, repository initialization, file staging, and version control operations.

CI Python 3.9+ Code style: black Typed with mypy

Features

  • init - Initialize a new Git repository
  • add - Stage files to the index
  • commit - Create commit objects
  • status - Show working directory status
  • hash-object - Compute SHA-1 hash of files
  • cat-file - Display Git object content/type
  • ls-tree - List tree object contents
  • ls-files - Show staged files
  • write-tree - Create tree objects from index
  • clone - Clone remote repositories
  • push - Push commits to remote repositories
  • ls-remote - List remote references

Quick Start

Installation

git clone https://github.com/pypros/mini-git-python.git
cd mini-git-python
make setup
source venv/bin/activate

Basic Usage

# Initialize repository
mini-git init

# Stage and commit files
mini-git add README.md
mini-git status
mini-git commit -m "Initial commit"

# Clone repository
mini-git clone https://github.com/user/repo.git

Development

Prerequisites

  • Python 3.9+
  • Standard library only (no external dependencies)

Development Setup

# Setup development environment
make setup

# Activate virtual environment
source venv/bin/activate

# Run tests with formatting and linting
make test

# Run only tests
make test-only

# Format code
make format

# Check code quality
make lint

# Type checking
make typecheck

# Run all quality checks
make check-all

Available Make Commands

Command Description
make setup Create venv and install dependencies
make test Format, lint, and run tests
make test-only Run tests without formatting
make format Format code with black and isort
make lint Run flake8 linting
make typecheck Run mypy type checking
make check-all Run all quality checks
make clean Remove build artifacts and venv

Code Quality

  • Type Hints: Full type annotations with mypy
  • Documentation: Comprehensive docstrings
  • Testing: 35 unit tests with 100% pass rate
  • Formatting: Black + isort automatic formatting
  • Linting: Flake8 code quality checks
  • CI/CD: GitHub Actions automated testing

Architecture

Project Structure

mini-git-python/
├── git.py              # Main implementation
├── test_git.py         # Unit tests
├── setup.py            # Package configuration
├── Makefile            # Development automation
├── pyproject.toml      # Tool configuration
├── requirements-dev.txt # Development dependencies
└── README.md           # This file

Git Directory Structure

.git/
├── objects/            # Compressed Git objects
│   ├── xx/            # First 2 chars of SHA-1
│   └── pack/          # Packfiles
├── refs/              # Branch and tag references
│   ├── heads/         # Branch pointers
│   └── remotes/       # Remote tracking branches
├── index              # Staging area
└── HEAD               # Current branch pointer

Implementation Details

Core Components

  • Object Storage: SHA-1 based content addressing
  • Index Management: Binary staging area format
  • Packfile Support: Delta compression and unpacking
  • Smart HTTP Protocol: Remote repository operations
  • Tree/Blob Objects: File system representation

Supported Operations

  • Repository initialization and configuration
  • File staging and commit creation
  • Object hashing and retrieval
  • Remote repository cloning and pushing
  • Working directory status tracking

Testing

The project includes comprehensive unit tests covering:

  • Object manipulation and storage
  • Index operations and file staging
  • Remote protocol handling
  • Packfile processing
  • Error handling and edge cases
# Run all tests
make test

# Run specific test
python -m unittest test_git.TestMiniGitCLI.test_hash_object_success

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run make check-all
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Educational Purpose

This project demonstrates:

  • Git's internal object model
  • SHA-1 content addressing
  • Delta compression algorithms
  • Network protocol implementation
  • Binary file format handling
  • Version control system design