{"id":38752583,"url":"https://github.com/elsonwu/git-rs","last_synced_at":"2026-01-17T11:50:58.512Z","repository":{"id":311636888,"uuid":"1044330283","full_name":"elsonwu/git-rs","owner":"elsonwu","description":"A lightweight Git clone built in Rust, created as a learning project.","archived":false,"fork":false,"pushed_at":"2025-08-25T16:09:23.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-25T18:11:48.812Z","etag":null,"topics":["git","learning-by-doing","rust"],"latest_commit_sha":null,"homepage":"https://elsonwu.github.io/git-rs/","language":"Rust","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/elsonwu.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}},"created_at":"2025-08-25T14:18:16.000Z","updated_at":"2025-08-25T16:11:24.000Z","dependencies_parsed_at":"2025-08-25T18:12:12.956Z","dependency_job_id":"44201a43-22a6-4928-a926-b989530ba46d","html_url":"https://github.com/elsonwu/git-rs","commit_stats":null,"previous_names":["elsonwu/git-rs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/elsonwu/git-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsonwu%2Fgit-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsonwu%2Fgit-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsonwu%2Fgit-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsonwu%2Fgit-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elsonwu","download_url":"https://codeload.github.com/elsonwu/git-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsonwu%2Fgit-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["git","learning-by-doing","rust"],"created_at":"2026-01-17T11:50:58.414Z","updated_at":"2026-01-17T11:50:58.492Z","avatar_url":"https://github.com/elsonwu.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git-RS: Educational Git Implementation 🦀\n\n[![CI](https://github.com/elsonwu/git-rs/workflows/CI/badge.svg)](https://github.com/elsonwu/git-rs/actions/workflows/ci.yml)\n[![Documentation](https://github.com/elsonwu/git-rs/workflows/Documentation/badge.svg)](https://github.com/elsonwu/git-rs/actions/workflows/docs.yml)\n[![Quality](https://github.com/elsonwu/git-rs/workflows/Quality/badge.svg)](https://github.com/elsonwu/git-rs/actions/workflows/quality.yml)\n[![Maintenance](https://github.com/elsonwu/git-rs/workflows/Maintenance/badge.svg)](https://github.com/elsonwu/git-rs/actions/workflows/maintenance.yml)\n\nA minimal Git implementation in Rust designed for learning Git internals and understanding how version control systems work under the hood.\n\n## 🎯 Project Goals\n\nThis project implements core Git functionality from scratch to understand:\n\n- How Git stores objects (blobs, trees, commits) using content-addressed storage\n- How the staging area (index) works as a three-way merge preparation\n- How references and branches are managed through the filesystem\n- Git's object model and SHA-1 hash-based storage system\n- How Git tracks file changes across working directory, staging area, and commits\n\n## ⚠️ Important: Flexible Repository Structure\n\nGit-rs supports two modes for different learning and testing needs:\n\n### 🎓 Educational Mode (Default - Safe for Learning)\n\nWhen you run `git-rs init`, it creates:\n\n- `.git-rs/` directory (not `.git/`)\n- `.git-rs/git-rs-index` file (not `.git/index`)\n\nThis allows you to:\n\n- Run git-rs commands in existing Git repositories without conflicts\n- Compare git-rs behavior with real Git side-by-side\n- Learn safely without affecting your actual Git workflow\n\n### 🔄 Git Compatibility Mode (Advanced - Real Git Interoperability)\n\nWhen you run `git-rs --git-compat init`, it creates:\n\n- `.git/` directory (standard Git structure)\n- `.git/index` file (standard Git index)\n\nThis enables you to:\n\n- Test git-rs output with real Git commands\n- Verify compatibility with existing Git tools\n- Switch between git-rs and git seamlessly\n\n**Examples:**\n\n```bash\n# Safe learning mode (default)\ngit-rs init                    # Creates .git-rs/\ngit-rs add file.txt           # Uses .git-rs/git-rs-index\n\n# Git compatibility mode  \ngit-rs --git-compat init      # Creates .git/\ngit-rs --git-compat add file.txt  # Uses .git/index\ngit status                    # Can use real Git to check!\n```\n\n## 🏗️ Architecture (Domain-Driven Design)\n\nThis project follows DDD principles with clean separation of concerns:\n\n```text\nsrc/\n├── main.rs              # CLI entry point with clap\n├── lib.rs               # Library exports and error handling\n├── domain/              # 🧠 Core business logic\n│   ├── repository.rs    # Repository aggregate root\n│   ├── objects.rs       # Git objects (Blob, Tree, Commit)\n│   ├── references.rs    # HEAD, branches, tags\n│   └── index.rs         # Staging area model\n├── infrastructure/      # 💾 Persistence layer\n│   ├── object_store.rs  # File-based object database\n│   ├── ref_store.rs     # Reference file management\n│   └── index_store.rs   # Index file serialization\n├── application/         # 🎯 Use cases (commands)\n│   ├── init.rs          # ✅ Repository initialization\n│   ├── add.rs           # ✅ File staging\n│   ├── status.rs        # ✅ Working tree status\n│   ├── commit.rs        # ✅ Commit creation\n│   ├── diff.rs          # ✅ Content comparison\n│   └── clone.rs         # ✅ Repository cloning\n└── cli/                 # 🖥️ Command line interface\n    └── commands.rs      # Command handlers and user interaction\n```\n\n**Layer Responsibilities:**\n\n- **Domain**: Pure business logic, no I/O dependencies\n- **Infrastructure**: File system operations, serialization\n- **Application**: Orchestrates domain and infrastructure\n- **CLI**: User interface and command parsing\n\n## 📊 Git Internals: Visual Guide\n\n### Repository Structure (.git-rs/)\n\n```text\n.git-rs/\n├── objects/              # Content-addressed object database\n│   ├── 5a/\n│   │   └── 1b2c3d...    # Blob object (file content)\n│   ├── ab/\n│   │   └── cd1234...    # Tree object (directory listing)\n│   └── ef/\n│       └── 567890...    # Commit object (snapshot + metadata)\n├── refs/                 # Reference storage\n│   ├── heads/           # Branch references\n│   │   ├── main         # Contains: \"5abc123def...\"\n│   │   └── feature-x    # Contains: \"7def456ghi...\"\n│   └── tags/            # Tag references\n├── HEAD                  # Current branch pointer\n├── git-rs-index         # Staging area (JSON format)\n├── config               # Repository configuration\n└── description          # Repository description\n```\n\n### Object Storage Model\n\n```text\nWorking Directory  →  Staging Area  →  Repository\n     (files)           (git-rs-index)    (objects/)\n        │                    │              │\n        │── git add ─────────▶              │\n        │                    │── commit ───▶\n        │◀────────── checkout ──────────────│\n```\n\n### Hash-Based Object System\n\n```text\nObject Content → SHA-1 Hash → Storage Path\n\"Hello World\"  → a1b2c3...  → .git-rs/objects/a1/b2c3...\n\nObject Format:\n\"\u003ctype\u003e \u003csize\u003e\\0\u003ccontent\u003e\"\n\"blob 11\\0Hello World\"\n```\n\n## 🔧 Implemented Commands\n\n### ✅ `git-rs init` - Repository Initialization\n\n**What it does:**\n\n- Creates `.git-rs/` directory structure\n- Initializes object database with proper subdirectories\n- Sets up reference system (HEAD pointing to refs/heads/main)\n- Creates configuration files\n\n**Educational Insights:**\n\n- How Git creates a repository from scratch\n- Directory structure and file organization\n- Reference initialization and HEAD management\n\n**Example:**\n\n```bash\ngit-rs init\n# Creates: .git-rs/{objects,refs/{heads,tags},HEAD,config,description}\n```\n\n### ✅ `git-rs add` - File Staging\n\n**What it does:**\n\n- Reads file content and calculates SHA-1 hash\n- Creates blob objects in object database with zlib compression\n- Updates staging area (git-rs-index) with file paths and hashes\n- Handles multiple files and directory recursion\n\n**Educational Insights:**\n\n- Content-addressed storage: identical content = same hash = same object\n- How Git tracks file changes through content hashing\n- The role of the staging area in preparing commits\n- Object creation and compression techniques\n\n**Example:**\n\n```bash\ngit-rs add README.md src/\n# Creates blob objects and updates git-rs-index\n```\n\n**Internal Process:**\n\n1. Read file content: `\"Hello World\"`\n2. Create blob: `\"blob 11\\0Hello World\"`\n3. Calculate hash: `SHA-1(\"blob 11\\0Hello World\") = 5ab2c3d...`\n4. Store compressed object: `.git-rs/objects/5a/b2c3d...`\n5. Update index: `{\"README.md\": {\"hash\": \"5ab2c3d...\", ...}}`\n\n### ✅ `git-rs status` - Working Tree Status\n\n**What it does:**\n\n- Compares working directory against staging area and last commit\n- Categorizes file changes: staged, modified, deleted, untracked\n- Shows current branch and commit information\n- Respects `.gitignore` patterns\n\n**Educational Insights:**\n\n- Git's \"three trees\" concept: working directory, index, HEAD\n- How Git determines file status through hash comparison\n- The relationship between different file states\n- Gitignore pattern matching\n\n**Status Categories:**\n\n```text\nChanges to be committed:     # In index, different from HEAD\n  new file:   README.md\n  modified:   src/main.rs\n\nChanges not staged:          # In working dir, different from index  \n  modified:   README.md\n  deleted:    old_file.txt\n\nUntracked files:            # In working dir, not in index\n  new_feature.rs\n```\n\n### ✅ `git-rs commit` - Commit Creation\n\n**What it does:**\n\n- Creates tree objects from staged files in index\n- Generates commit objects with metadata (author, timestamp, message)\n- Updates branch references to point to new commit\n- Handles both root commits and commits with parents\n- Validates commit messages and detects empty commits\n\n**Educational Insights:**\n\n- How Git creates immutable snapshots from staged changes\n- Tree object construction and hierarchical file organization\n- Commit object format with parent relationships\n- Reference management and branch pointer updates\n- The difference between root commits and regular commits\n\n**Example:**\n\n```bash\ngit-rs commit -m \"Initial implementation\"\n# Creates tree object, commit object, and updates branch ref\n```\n\n**Internal Process:**\n\n1. Load staged files from index: `git-rs-index`\n2. Create tree entries: `{name: \"README.md\", mode: 100644, hash: \"5ab2c3d...\"}`\n3. Store tree object: `tree 42\\0\u003ctree-content\u003e` → `7def456ghi...`\n4. Create commit object with:\n   - Tree hash: `7def456ghi...`\n   - Parent commits (if any)\n   - Author/committer signatures\n   - Commit message\n5. Store commit object: `commit 156\\0\u003ccommit-content\u003e` → `9abc123def...`\n6. Update branch reference: `.git-rs/refs/heads/main` → `9abc123def...`\n\n**Commit Object Format:**\n\n```text\ntree 7def456ghi789...\nparent 1abc234def567... (if not root commit)\nauthor John Doe \u003cjohn@example.com\u003e 1692000000 +0000\ncommitter John Doe \u003cjohn@example.com\u003e 1692000000 +0000\n\nInitial implementation\n```\n\n### ✅ `git-rs diff` - Content Comparison\n\n**What it does:**\n\n- Generates unified diff format output showing line-by-line changes\n- Compares working directory vs staging area (default)\n- Compares staging area vs last commit (with `--cached`)\n- Detects binary files and handles them appropriately\n- Shows file headers and line context for all changes\n\n**Educational Insights:**\n\n- How diff algorithms work to compare file contents\n- Understanding unified diff format used by patch tools\n- The difference between staged and unstaged changes\n- Binary file detection and handling strategies\n\n**Example:**\n\n```bash\n# Show unstaged changes\ngit-rs diff\n\n# Show staged changes  \ngit-rs diff --cached\n```\n\n**Output Format:**\n\n```diff\ndiff --git a/README.md b/README.md\nindex 1234567..abcdefg 100644\n--- a/README.md\n+++ b/README.md\n@@ -1,3 +1,4 @@\n # Git-RS\n \n-Old line\n+New line\n+Added line\n```\n\n### ✅ `git-rs clone` - Repository Cloning\n\nComplete HTTP-based repository cloning with educational insights.\n\n```bash\n# Clone to directory with same name as repository\ngit-rs clone https://github.com/user/repo.git\n\n# Clone to custom directory name\ngit-rs clone https://github.com/user/repo.git my-project\n\n# Clone specific branch\ngit-rs clone --branch develop https://github.com/user/repo.git\n```\n\n**Features:**\n\n- HTTP Git protocol implementation\n- Pack file transfer and processing\n- Remote reference discovery and mapping\n- Working directory checkout\n- Educational wire protocol documentation\n\n## 🚧 Future Commands (Planned)\n\n### � `git-rs log` - Commit History\n\n**Status**: Not yet implemented (placeholder exists in CLI)\n\n```bash\ngit-rs log           # Show all commit history\ngit-rs log -n 5      # Show last 5 commits\n```\n\n**Will implement:**\n\n- Commit graph traversal and display\n- Parent relationship following\n- Chronological sorting with metadata\n- Formatted history output\n\n### �🔄 Branch Operations\n\n```bash\ngit-rs status\n# Shows comprehensive file state analysis\n```\n\n## 🧮 Hash Calculation Deep Dive\n\nGit uses SHA-1 content addressing for all objects:\n\n```rust\n// Object format: \"\u003ctype\u003e \u003csize\u003e\\0\u003ccontent\u003e\"\nlet blob_content = b\"Hello World\";\nlet object_content = format!(\"blob {}\\0\", blob_content.len());\nlet full_content = [object_content.as_bytes(), blob_content].concat();\nlet hash = sha1::digest(\u0026full_content); // \"5ab2c3d4e5f6...\"\n```\n\n**Why this matters:**\n\n- Identical content produces identical hashes\n- Deduplication: same file content stored only once\n- Integrity: any corruption changes the hash\n- Distributed: objects can be safely shared between repositories\nOur test suite covers:\n\n- **Unit tests**: Individual component behavior\n- **Integration tests**: Command workflows\n- **Property tests**: Hash consistency, object integrity\n- **Cross-platform tests**: macOS, Linux compatibility (Windows not supported)\n\n```bash\ncargo test                    # Run all tests\ncargo test --test integration # Integration tests only\ncargo test domain::          # Domain layer tests\n```\n\n## 🚀 Usage Examples\n\n### Basic Workflow\n\n```bash\n# Initialize repository\ngit-rs init\n\n# Add files to staging\ngit-rs add README.md src/\n\n# Check status\ngit-rs status\n\n# Create commit\ngit-rs commit -m \"Initial implementation\"\n\n# View differences (when implemented)\ngit-rs diff\ngit-rs diff --staged\n```\n\n### Educational Exploration\n\n```bash\n# Examine object database\nfind .git-rs/objects -type f\nfile .git-rs/objects/5a/b2c3d4...\n\n# View staging area\ncat .git-rs/git-rs-index | jq .\n\n# Check references\ncat .git-rs/HEAD\ncat .git-rs/refs/heads/main\n```\n\n## 🎓 Learning Outcomes\n\nAfter exploring this implementation, you'll understand:\n\n1. **Git's Object Model**: How blobs, trees, and commits form a directed acyclic graph\n2. **Content Addressing**: Why identical content produces identical hashes\n3. **Three Trees**: Working directory, index, and HEAD relationships\n4. **Reference System**: How branches and tags are just pointers to commits\n5. **Staging Process**: Why the index exists and how it enables powerful workflows\n6. **File System Integration**: How Git maps its abstract model to disk storage\n\n## 🔍 Debugging and Introspection\n\nUse these commands to explore git-rs internals:\n\n```bash\n# Object inspection\nhexdump -C .git-rs/objects/5a/b2c3d4...\n\n# Decompression (requires zlib tools)\nzpipe -d \u003c .git-rs/objects/5a/b2c3d4...\n\n# Index inspection  \njq . .git-rs/git-rs-index\n\n# Reference tracking\nfind .git-rs/refs -type f -exec echo {} \\; -exec cat {} \\;\n```\n\n## 📚 Educational Resources\n\nEach command implementation includes:\n\n- **Comprehensive documentation**: What, why, and how\n- **Visual diagrams**: ASCII art showing data flow\n- **Code examples**: Real-world usage patterns\n- **Test cases**: Behavior verification\n- **Comparison with Git**: How our implementation differs/matches\n\n## 📖 Documentation\n\n### 📚 Core Documentation\n\n- **[🏗️ Architecture Guide](docs/ARCHITECTURE.md)** - System design and Git internals deep dive\n- **[⚡ Command Reference](docs/COMMANDS.md)** - Complete reference for all implemented commands\n- **[🔍 Git Internals Explained](docs/GIT_INTERNALS.md)** - Educational exploration of Git concepts\n- **[📊 Project Status](docs/STATUS.md)** - Development roadmap and contribution guidelines\n- **[🦀 API Documentation](https://elsonwu.github.io/git-rs/)** - Generated Rust API docs\n\n### 🎯 Learning Paths\n\n**For Git Beginners:**\n\n1. Start with this README for project overview\n2. Read [Git Internals Explained](docs/GIT_INTERNALS.md) to understand core concepts\n3. Try hands-on examples in [Command Reference](docs/COMMANDS.md)\n4. Explore [Architecture Guide](docs/ARCHITECTURE.md) for implementation details\n\n**For Developers:**\n\n1. Review [Project Status](docs/STATUS.md) for current state and roadmap\n2. Study [Architecture Guide](docs/ARCHITECTURE.md) for system design\n3. Check [API Documentation](https://elsonwu.github.io/git-rs/) for code reference\n4. Follow contribution guidelines below\n\n**For Rust Learners:**\n\n1. Examine [Architecture Guide](docs/ARCHITECTURE.md) for Domain-Driven Design patterns\n2. Browse [API Documentation](https://elsonwu.github.io/git-rs/) for Rust idioms\n3. Look at GitHub Actions workflows in `.github/workflows/` for CI/CD examples\n\n### 🔍 Key Concepts You'll Learn\n\n- **Git Object Model**: How blobs, trees, and commits form a directed acyclic graph\n- **Content Addressing**: SHA-1 hashing and object identification system\n- **Three Trees**: Working directory, index, and HEAD relationships\n- **Reference System**: How branches and tags are pointers to commits\n- **Domain-Driven Design**: Clean architecture with separated concerns in Rust\n- **Testing Strategies**: Unit tests, integration tests, and property-based testing\n\n### 🆘 Getting Help\n\n- **Git concepts questions**: Check [Git Internals Explained](docs/GIT_INTERNALS.md)\n- **Usage questions**: See [Command Reference](docs/COMMANDS.md)\n- **Implementation questions**: Review [Architecture Guide](docs/ARCHITECTURE.md)\n- **Bug reports**: Open an issue on [GitHub](https://github.com/elsonwu/git-rs/issues)\n- **Feature requests**: Check [Project Status](docs/STATUS.md) first, then open an issue\n\n## 🤝 Contributing\n\nThis is primarily an educational project, but contributions are welcome:\n\n- Bug fixes and improvements\n- Additional test cases\n- Documentation enhancements\n- Performance optimizations\n- New command implementations\n\n### Development Setup\n\nBefore committing changes, ensure code quality with our formatting script:\n\n```bash\n# Run all formatting and checks\n./scripts/format.sh\n\n# Or manually run individual tools:\ncargo fmt                    # Rust code formatting\nmarkdownlint-cli2 --fix \"**/*.md\" \"!target/**\" \"!node_modules/**\"  # Markdown formatting\ncargo clippy --all-targets --all-features -- -D warnings  # Linting\ncargo test                   # Test suite\n```\n\n## 📖 References\n\n- [Git Internals Book](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects)\n- [Git Source Code](https://github.com/git/git)\n- [Pro Git Book](https://git-scm.com/book)\n- [Git Object Model](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects)\n\n---\n\n**Remember**: This implementation uses `.git-rs/` directories to avoid conflicts with real Git repositories, making it safe to experiment with in existing projects!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felsonwu%2Fgit-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felsonwu%2Fgit-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felsonwu%2Fgit-rs/lists"}