{"id":32335663,"url":"https://github.com/marincervinschi/vestigium","last_synced_at":"2026-04-08T23:34:28.197Z","repository":{"id":314132817,"uuid":"1053960601","full_name":"MarinCervinschi/Vestigium","owner":"MarinCervinschi","description":"Vestigium is my educational implementation that focuses on Git's local operations - the fundamental building blocks that make version control possible. ","archived":false,"fork":false,"pushed_at":"2025-09-29T08:57:05.000Z","size":1731,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T10:27:40.162Z","etag":null,"topics":["ci-cd","codecov","docker","docker-compose","git","linux","pytest","python","shell","tests","version-control"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarinCervinschi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T07:08:51.000Z","updated_at":"2025-09-29T08:57:09.000Z","dependencies_parsed_at":"2025-09-10T20:44:21.013Z","dependency_job_id":"4c5cf9ef-2bfb-4c42-832b-a955318d584b","html_url":"https://github.com/MarinCervinschi/Vestigium","commit_stats":null,"previous_names":["marincervinschi/vestigium"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MarinCervinschi/Vestigium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FVestigium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FVestigium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FVestigium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FVestigium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarinCervinschi","download_url":"https://codeload.github.com/MarinCervinschi/Vestigium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FVestigium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280699783,"owners_count":26375697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci-cd","codecov","docker","docker-compose","git","linux","pytest","python","shell","tests","version-control"],"created_at":"2025-10-23T21:48:02.006Z","updated_at":"2025-10-23T21:48:06.622Z","avatar_url":"https://github.com/MarinCervinschi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vestigium 🫆🌳\n\n[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen.svg)](https://pre-commit.com/)\n[![CI Tests](https://github.com/MarinCervinschi/Vestigium/actions/workflows/ci.yml/badge.svg)](https://github.com/MarinCervinschi/Vestigium/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/MarinCervinschi/Vestigium/branch/main/graph/badge.svg)](https://codecov.io/gh/MarinCervinschi/Vestigium)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/vestigium_logo.png\" alt=\"Vestigium Logo\" width=\"400\" /\u003e\n\u003c/p\u003e\n\nA 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.\n\n## About This Project\n\nVestigium 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:\n\n- How Git stores objects (blobs, trees, commits, tags) using SHA-1 hashing\n- The structure and purpose of the `.git` directory (I call it `.ves` here)\n- How the index (staging area) works internally\n- Reference management (branches, tags, HEAD)\n- Object compression and storage strategies\n- The relationship between working tree, index, and repository\n\n**My Goal**: Demystify Git's \"magic\" by building a compatible implementation that reveals the elegant simplicity behind version control.\n\n## 📚 Technical Documentation\n\nFor a deep dive into Git's internal concepts and how they're implemented in Vestigium, check out the **comprehensive technical documentation**:\n\n**📖 [Complete Documentation Guide](docs/README.md)**\n\nThis documentation covers:\n\n- **Core Concepts**: Repository structure, object system, staging area, references\n- **Essential Operations**: Tree operations, file filtering, status computation\n- **Supporting Systems**: Configuration, text parsing, utility infrastructure\n- **Practical Usage**: Complete command reference with examples\n\nThe 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.\n\n## Repository Overview\n\nThis is how I've organized my codebase to mirror Git's internal structure:\n\n```\nsrc/\n├── cli.py              # Argument parsing controller\n├── libves.py           # Main entry point\n├── commands/           # Individual command implementations\n│   ├── init.py         # Repository initialization\n│   ├── add.py          # Staging area management\n│   ├── commit.py       # Creating commits\n│   ├── status.py       # Working tree status\n│   └── ...             # Other Git-like commands\n├── core/               # Core Git mechanisms\n│   ├── repository.py   # Repository structure and management\n│   ├── objects.py      # Object storage (blob, tree, commit, tag)\n│   ├── index.py        # Staging area implementation\n│   └── refs.py         # Reference management\n└── utils/              # Helper modules\n    ├── tree.py         # Tree traversal and manipulation\n    ├── status.py       # Status comparison algorithms\n    └── config.py       # Configuration handling\n```\n\n## Features\n\n- **Educational focus**: I've written clean, readable code with extensive comments to document my learning journey\n- **Git compatibility**: I use the same object formats and hashing as Git\n- **Modular architecture**: I've separated CLI, core logic, and command implementations\n- **Comprehensive testing**: I've built a full test suite covering all major functionality\n- **Docker support**: I've set up an isolated testing environment with Docker Compose\n- **CI/CD**: I've automated testing with GitHub Actions\n\n## Installation\n\n### Local Development\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/MarinCervinschi/Vestigium.git\ncd Vestigium\n```\n\n2. Install in development mode with dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n3. Make the executable script runnable:\n\n```bash\nchmod +x ./ves\n```\n\n### Docker Development\n\nFor a clean, isolated environment:\n\n```bash\n# Start development environment\ndocker compose run --rm vestigium-dev\n```\n\n## Usage\n\n### Available Commands\n\nFor detailed usage and examples of all commands, see [COMMANDS.md](docs/COMMANDS.md).\n\n**Basic Commands:**\n\n- `init` - Initialize a new repository\n- `add` - Add files to staging area\n- `commit` - Record changes to repository\n- `status` - Show working tree status\n- `checkout` - Extract commit to directory\n\n**Object Management:**\n\n- `hash-object` - Calculate and store file hash\n- `cat-file` - Display object content\n\n**Navigation \u0026 History:**\n\n- `log` - Show commit history\n- `ls-files` - List files in index\n- `ls-tree` - List tree contents\n\n**References \u0026 Tags:**\n\n- `tag` - Create and list tags\n- `show-ref` - Show all references\n- `rev-parse` - Resolve identifiers\n\n**Utilities:**\n\n- `rm` - Remove files from index\n- `check-ignore` - Verify ignore rules\n\n## Development\n\n### Code Quality Tools\n\nThis project uses several tools to maintain code quality:\n\n```bash\n# Format code with Black\nblack src/ tests/\n\n# Sort imports with isort\nisort src/ tests/\n\n# Type checking with MyPy\nmypy src/\n\n# Run all quality checks\nblack src/ tests/ \u0026\u0026 isort src/ tests/ \u0026\u0026 mypy src/\n```\n\n### Testing\n\n#### Unit Tests (Docker - Recommended)\n\n```bash\n# Run only unit tests (excluding stress tests)\ndocker compose run --rm vestigium-unit\n\n# Run all tests (unit + stress tests)\ndocker compose run --rm vestigium-test\n\n# Development environment with all tools available\ndocker compose run --rm vestigium-dev\n```\n\n#### Stress/Performance Tests\n\nFor performance testing with large files and numerous files:\n\n```bash\n# Run stress tests in Docker\ndocker compose run --rm vestigium-stress\n```\n\nThe stress tests evaluate:\n\n- **Large file performance**: Files from 1MB to 50MB\n- **Many files performance**: From 50 to 1000+ files\n- **Mixed operations**: Complex scenarios with various file types\n- **Memory usage**: Monitoring resource consumption during operations\n\n\u003e**Note**: For more details, see the [Stress Tests Documentation](docs/STRESS_TESTS.md).\n\n#### Local Testing\n\n```bash\n# Run unit tests locally (excluding stress tests)\npytest tests/ -v -m \"not stress\"\n\n# Run all tests locally (unit + stress)\npytest tests/ -v\n\n# Run tests with coverage (unit tests only)\npytest --cov=src --cov-report=term-missing -m \"not stress\"\n\n# Generate HTML coverage report (unit tests only)\npytest --cov=src --cov-report=html -m \"not stress\"\n\n# Run stress tests locally (not recommended - use Docker instead)\npytest tests/stress/ -v -m stress\n```\n\n**Note**: Stress tests create large temporary files and may consume significant system resources. Using Docker is strongly recommended for isolation and consistent results.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarincervinschi%2Fvestigium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarincervinschi%2Fvestigium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarincervinschi%2Fvestigium/lists"}