{"id":49389783,"url":"https://github.com/warriorssami/bit","last_synced_at":"2026-04-28T12:04:24.193Z","repository":{"id":338111430,"uuid":"918759118","full_name":"WarriorsSami/bit","owner":"WarriorsSami","description":"A lil' Bit of Git","archived":false,"fork":false,"pushed_at":"2026-04-15T21:15:49.000Z","size":496,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-15T23:23:06.534Z","etag":null,"topics":["dsa","git","tdd"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WarriorsSami.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-01-18T19:26:17.000Z","updated_at":"2026-04-15T21:15:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WarriorsSami/bit","commit_stats":null,"previous_names":["warriorssami/bit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WarriorsSami/bit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WarriorsSami%2Fbit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WarriorsSami%2Fbit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WarriorsSami%2Fbit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WarriorsSami%2Fbit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WarriorsSami","download_url":"https://codeload.github.com/WarriorsSami/bit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WarriorsSami%2Fbit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32379631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T11:25:28.583Z","status":"ssl_error","status_checked_at":"2026-04-28T11:25:05.435Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["dsa","git","tdd"],"created_at":"2026-04-28T12:04:21.948Z","updated_at":"2026-04-28T12:04:24.181Z","avatar_url":"https://github.com/WarriorsSami.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bit - Just a lil' bit of Git in Rust\n\nA Git implementation written in Rust, inspired by James Coglan’s book [\"Building Your Own Git\"](https://shop.jcoglan.com/building-git/). `bit` is intentionally educational, but it is built with production-style engineering discipline: explicit domain modeling, invariant-driven design, and a strong test suite.\n\n## Overview\n\n`bit` models Git as interactions between four core areas:\n\n- **Object database** (`.git/objects`): immutable content-addressed objects.\n- **Index** (`.git/index`): staging-area metadata and next-tree blueprint.\n- **References** (`.git/HEAD`, `refs/*`): symbolic and direct pointers into history.\n- **Workspace**: mutable files checked out for editing.\n\nMost command behavior can be reasoned about as transitions across these areas.\n\n## Implemented Commands\n\n- ✅ `bit init`\n- ✅ `bit hash-object`\n- ✅ `bit ls-tree`\n- ✅ `bit add`\n- ✅ `bit commit`\n- ✅ `bit status`\n- ✅ `bit diff`\n- ✅ `bit branch` (create/list/delete)\n- ✅ `bit checkout`\n- ✅ `bit log`\n- ✅ `bit merge` (multi-scenario DAG merges, conflict-aware behavior)\n\n## Domain Models and Invariants\n\n### 1) Object model\n- Supports Git object categories needed by current commands (blob/tree/commit flows).\n- Serialization follows Git format: `\u003ctype\u003e \u003csize\u003e\\0\u003ccontent\u003e`.\n- Object IDs are SHA-1 of serialized object bytes.\n- Objects are immutable once written.\n\n### 2) Index model\n- Entries are deterministically ordered.\n- Header entry count reflects serialized entries.\n- Index checksum verifies integrity.\n- Parent/child path conflicts are normalized when replacing file/dir shapes.\n- Index read/write uses locking semantics to maintain consistency under concurrent operations.\n\n### 3) Revision + refs model\n- Branch and revision parsing supports common forms (`ref`, `^`, `~n`, aliases).\n- Branch name validation follows Git-like constraints and explicit parser rules.\n- HEAD and refs are managed as first-class repository state.\n\n### 4) Merge and graph model\n- Merge behavior is validated on multiple non-trivial commit DAGs.\n- Best common ancestor scenarios and branching edge-cases are covered by integration tests.\n\n\n### 5) Diff and patch model\n- Diff endpoints are explicit (`workspace↔index`, `index↔HEAD`, `rev↔rev`).\n- File-level status (`A`,`D`,`M`, mode-only changes) is deterministic.\n- Patch hunks should remain stable in ordering and context output semantics.\n\n### 6) Log traversal model\n- Traversal honors included and excluded revision expressions.\n- Commit output ordering should be deterministic, including tie-breaking for identical timestamps.\n- Decorations are a read-only projection of current refs over commits.\n\n### 7) Checkout migration model\n- Checkout is a controlled migration between revisions across refs, index, and workspace.\n- Safety checks should prevent silent clobbering of local/staged work.\n- Success means workspace/index are synchronized to target tree semantics.\n\n### 8) Core algorithms and data structures\n- **Merkle DAG** for commit/history integrity and reachability.\n- **Tree/index path hierarchy (trie-like)** for parent/child path operations.\n- **Revision AST** to represent references, parent (`^`), ancestor (`~n`), ranges, and exclusions.\n- **Myers-style diff baseline** for minimal edit script patch construction (future enhancements may refine heuristics).\n- **Binary codec discipline** for future wire protocol framing and pack parsing.\n\n## Rust Engineering Practices\n\nThis project emphasizes:\n\n- idiomatic ownership and borrowing,\n- explicit `Result`-based error handling,\n- deterministic filesystem interaction,\n- lock-aware repository mutations,\n- incremental changes with strong test coverage.\n\n## Architecture\n\n```text\nsrc/\n├── main.rs              # CLI interface and command routing\n├── commands/            # Command implementations\n│   ├── plumbing/        # Low-level Git commands\n│   └── porcelain/       # User-facing commands\n├── areas/               # Repository areas: database/index/refs/workspace\n└── artifacts/           # Domain objects and algorithms (objects, diff, merge, log, status)\n```\n\n## How to Run Locally\n\n### Prerequisites\n\n- Rust 1.93 or later\n- Cargo\n\n### Build\n\n```bash\ncargo build --release\n```\n\nBinary path:\n\n```bash\ntarget/release/bit\n```\n\n## Usage\n\n```bash\n# initialize repository\nbit init [path]\n\n# write or hash objects\nbit hash-object [-w] \u003cfile\u003e\nbit ls-tree [-r] \u003ctree-sha\u003e\n\n# staging + commits\nbit add \u003cpath\u003e...\nbit commit -m \"message\"\n\n# inspect state\nbit status [--porcelain]\nbit diff [--cached] [--name-status] [--diff-filter=ADMR] [old] [new]\nbit log [targets...] [-- --paths] [--oneline] [--abbrev-commit] [--decorate=\u003cnone|short|full\u003e] [--patch]\n\n# branch / checkout / merge\nbit branch create \u003cname\u003e [source]\nbit branch list [-v]\nbit branch delete \u003cname\u003e... [-f]\nbit checkout \u003ctarget-revision\u003e\nbit merge \u003ctarget-revision\u003e -m \"merge message\"\n```\n\n## Testing\n\nThe test suite combines unit, property-based, and integration tests to validate Git semantics.\n\n### Environment setup\n\n```bash\nmkdir -p ../playground\n```\n\n### Run tests\n\n```bash\ncargo test\ncargo test -- --nocapture\n```\n\nTargeted examples:\n\n```bash\ncargo test add\ncargo test commit\ncargo test diff\ncargo test log\ncargo test merge\n```\n\n## Testing Strategy (TDD + Coglan-style semantics)\n\n### TDD loop\n1. Write a failing test from behavior/spec.\n2. Implement minimum code to pass.\n3. Refactor while preserving green tests.\n\n### Unit tests\nUse for pure logic and parsers:\n- revision syntax,\n- branch-name validation,\n- object payload formatting/parsing,\n- small deterministic transforms.\n\n### Property tests (`proptest`)\nUse for invariant-heavy behavior:\n- valid/invalid revision and branch grammar,\n- parser determinism,\n- boundary input spaces.\n\nStore generated failing cases in `proptest-regressions/` when applicable.\n\n### Integration tests\nUse command-level scenarios under `tests/`:\n- compare command output and state transitions,\n- cover merge graph topologies,\n- validate index/workspace/ref interactions,\n- compare against `git` where practical.\n\n\n### Merge / diff / log invariant tests to prioritize\n- **Merge**: fast-forward eligibility, criss-cross BCAs, multi-parent lineage ordering, conflict marker persistence.\n- **Diff**: endpoint correctness, mode-only changes, multi-file hunk stability, deterministic status ordering.\n- **Log**: include/exclude revision expressions, path-filtered history, stable ordering with timestamp ties, decoration rendering variants.\n\n### Remote + pack tests (future)\n- pkt-line codec round-trips and malformed-frame rejection.\n- negotiation state-machine tests for `want/have/ack` flows.\n- pack decoding tests for full objects and chained deltas.\n- object-integrity checks after unpack + write.\n\n## Roadmap aligned with *Building Git from Scratch*\n\n\u003e The roadmap is organized by domain themes that mirror the book’s progression from low-level object mechanics to higher-level collaboration/storage concerns.\n\n### A. Object storage and plumbing\n- [x] Initialize repository structure\n- [x] Hash/write loose objects\n- [x] Read/tree-walk object structures\n- [ ] Additional plumbing introspection and validation commands\n\n### B. Index and snapshot construction\n- [x] Stage files and directory trees\n- [x] Handle file/dir replacement conflicts\n- [x] Persist and validate index metadata/checksum\n- [ ] Interactive staging (`add -p`)\n\n### C. Commit graph and history traversal\n- [x] Write commits and parent relationships\n- [x] Traverse history for `log`\n- [x] Revision expressions and branch-based targeting\n- [ ] Extended ancestry/query expressions parity\n\n### D. Workspace inspection and patching\n- [x] `status` for staged/unstaged/untracked states\n- [x] `diff` for workspace/index/commit comparisons\n- [x] Patch-oriented log output\n- [ ] More advanced diff heuristics and rename/copy tracking\n\n### E. Branching, checkout, merge\n- [x] Branch create/list/delete\n- [x] Checkout with ref/symbolic-ref behavior\n- [x] Merge for complex DAG scenarios (including multi-BCA patterns)\n- [ ] More complete conflict resolution UX\n- [ ] Rebase/cherry-pick workflows\n\n### F. Remotes and packed storage\n- [ ] Clone/fetch/push/pull protocols\n- [ ] Packfiles and delta compression\n- [ ] Reflog, hooks, and GC lifecycle tooling\n\n\n#### Remote flow and pack protocol (expanded)\n- **Transport handshake/capabilities**: model protocol v2 style negotiation (capabilities, command selection, shallow/filter options where relevant).\n- **Object negotiation**: exchange `want`/`have` sets and ACK states to minimize transfer.\n- **Pack stream framing**: use pkt-line length-prefixed binary records with flush/delim packets.\n- **Pack data model**: support object entry headers, base/delta representations (`OFS_DELTA`, `REF_DELTA`), and integrity verification at stream/repo boundaries.\n- **Apply/delta pipeline**: decode + resolve base chains + reconstruct canonical objects before persistence.\n- **Safety invariants**: never accept malformed framing/checksums silently; keep object graph/hash checks explicit.\n\n## Known Gaps\n\n- No remote/network protocol support yet.\n- Packed object storage and delta compression are not implemented.\n- History-rewriting workflows (rebase/cherry-pick) are pending.\n- Merge UX can be improved for richer conflict presentation/resolution workflows.\n\n## Contributing\n\n1. Start from a failing test.\n2. Implement minimally.\n3. Keep changes small and focused.\n4. Ensure formatting and tests pass.\n5. Update README/instructions if behavior changes.\n\n## Acknowledgments\n\n- James Coglan for *Building Your Own Git*.\n- The Git project for behavioral reference.\n- The Rust ecosystem for excellent tooling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarriorssami%2Fbit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwarriorssami%2Fbit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarriorssami%2Fbit/lists"}