A simple Version Control System (VCS) built in Python for educational purposes. I created this project to understand and replicate the core local mechanisms of Git.
Vestigium is my educational implementation that focuses on Git's local operations - the fundamental building blocks that make version control possible. By recreating Git's internal mechanisms from scratch, I'm learning to understand:
- How Git stores objects (blobs, trees, commits, tags) using SHA-1 hashing
- The structure and purpose of the
.gitdirectory (I call it.veshere) - How the index (staging area) works internally
- Reference management (branches, tags, HEAD)
- Object compression and storage strategies
- The relationship between working tree, index, and repository
My Goal: Demystify Git's "magic" by building a compatible implementation that reveals the elegant simplicity behind version control.
For a deep dive into Git's internal concepts and how they're implemented in Vestigium, check out the comprehensive technical documentation:
📖 Complete Documentation Guide
This documentation covers:
- Core Concepts: Repository structure, object system, staging area, references
- Essential Operations: Tree operations, file filtering, status computation
- Supporting Systems: Configuration, text parsing, utility infrastructure
- Practical Usage: Complete command reference with examples
The docs explain why Git works the way it does rather than just how to use it - perfect for understanding the fundamental concepts that make version control possible.
This is how I've organized my codebase to mirror Git's internal structure:
src/
├── cli.py # Argument parsing controller
├── libves.py # Main entry point
├── commands/ # Individual command implementations
│ ├── init.py # Repository initialization
│ ├── add.py # Staging area management
│ ├── commit.py # Creating commits
│ ├── status.py # Working tree status
│ └── ... # Other Git-like commands
├── core/ # Core Git mechanisms
│ ├── repository.py # Repository structure and management
│ ├── objects.py # Object storage (blob, tree, commit, tag)
│ ├── index.py # Staging area implementation
│ └── refs.py # Reference management
└── utils/ # Helper modules
├── tree.py # Tree traversal and manipulation
├── status.py # Status comparison algorithms
└── config.py # Configuration handling
- Educational focus: I've written clean, readable code with extensive comments to document my learning journey
- Git compatibility: I use the same object formats and hashing as Git
- Modular architecture: I've separated CLI, core logic, and command implementations
- Comprehensive testing: I've built a full test suite covering all major functionality
- Docker support: I've set up an isolated testing environment with Docker Compose
- CI/CD: I've automated testing with GitHub Actions
- Clone the repository:
git clone https://github.com/MarinCervinschi/Vestigium.git
cd Vestigium- Install in development mode with dependencies:
pip install -e ".[dev]"- Make the executable script runnable:
chmod +x ./vesFor a clean, isolated environment:
# Start development environment
docker compose run --rm vestigium-devFor detailed usage and examples of all commands, see COMMANDS.md.
Basic Commands:
init- Initialize a new repositoryadd- Add files to staging areacommit- Record changes to repositorystatus- Show working tree statuscheckout- Extract commit to directory
Object Management:
hash-object- Calculate and store file hashcat-file- Display object content
Navigation & History:
log- Show commit historyls-files- List files in indexls-tree- List tree contents
References & Tags:
tag- Create and list tagsshow-ref- Show all referencesrev-parse- Resolve identifiers
Utilities:
rm- Remove files from indexcheck-ignore- Verify ignore rules
This project uses several tools to maintain code quality:
# Format code with Black
black src/ tests/
# Sort imports with isort
isort src/ tests/
# Type checking with MyPy
mypy src/
# Run all quality checks
black src/ tests/ && isort src/ tests/ && mypy src/# Run only unit tests (excluding stress tests)
docker compose run --rm vestigium-unit
# Run all tests (unit + stress tests)
docker compose run --rm vestigium-test
# Development environment with all tools available
docker compose run --rm vestigium-devFor performance testing with large files and numerous files:
# Run stress tests in Docker
docker compose run --rm vestigium-stressThe stress tests evaluate:
- Large file performance: Files from 1MB to 50MB
- Many files performance: From 50 to 1000+ files
- Mixed operations: Complex scenarios with various file types
- Memory usage: Monitoring resource consumption during operations
Note: For more details, see the Stress Tests Documentation.
# Run unit tests locally (excluding stress tests)
pytest tests/ -v -m "not stress"
# Run all tests locally (unit + stress)
pytest tests/ -v
# Run tests with coverage (unit tests only)
pytest --cov=src --cov-report=term-missing -m "not stress"
# Generate HTML coverage report (unit tests only)
pytest --cov=src --cov-report=html -m "not stress"
# Run stress tests locally (not recommended - use Docker instead)
pytest tests/stress/ -v -m stressNote: Stress tests create large temporary files and may consume significant system resources. Using Docker is strongly recommended for isolation and consistent results.
This project is licensed under the MIT License - see the LICENSE file for details.