Start Phase 2B implementation with documentation#8
Merged
Conversation
Add educational concept guides and API reference for pack files: Concept documents: - pack_files.md: Overview of pack file format, structure, and usage - delta_compression.md: Delta encoding/decoding algorithms - pack_index.md: Pack index format for fast object lookup API reference: - pack.md: Complete API docs for pack, pack_index, pack_writer, and delta modules Updates: - Link new docs from object_model.md and object_storage.md - Add see-also reference in storage.md API docs
Add new pack-related concept guides and API reference to nav: - Pack Files, Delta Compression, Pack Index under Concepts - Pack Objects API under API Reference
Add complete pack file implementation including: - delta.py: Delta encoding/decoding with INSERT and COPY instructions - pack_index.py: Pack index (version 2) for O(log n) object lookup - pack.py: Pack file reader with delta chain resolution - pack_writer.py: Pack file writer with optional delta compression - Updated ObjectDatabase with pack file support and repack method Includes comprehensive test coverage for all modules.
There was a problem hiding this comment.
Pull request overview
This pull request implements Phase 2B of the gitpy project, adding comprehensive support for Git pack files, including delta compression, pack indexes, and pack file writing capabilities. The changes introduce efficient object storage that complements the existing loose object storage with significant space savings through delta compression.
Key Changes:
- Implementation of Git's delta compression algorithm for efficient storage of similar objects
- Pack file reader supporting both undeltified and deltified objects (OFS_DELTA and REF_DELTA)
- Pack index implementation with O(log n) lookup using fanout tables and binary search
- Pack file writer with configurable delta compression and window-based similarity detection
- Integration with ObjectDatabase to seamlessly read from both loose objects and pack files
- Comprehensive test coverage with 5 new test files covering 1,693 lines of tests
- Extensive documentation with 3 new concept guides (2,483 lines) and 1 API reference (929 lines)
Reviewed changes
Copilot reviewed 19 out of 20 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
gitpy/storage/delta.py |
Delta compression implementation with parse, apply, and create functions |
gitpy/storage/pack.py |
Pack file reader with delta chain resolution and index integration |
gitpy/storage/pack_index.py |
Pack index with fanout table optimization for fast object lookup |
gitpy/storage/pack_writer.py |
Pack file writer with delta compression and sliding window algorithm |
gitpy/storage/database.py |
Enhanced ObjectDatabase with pack file support and repack functionality |
gitpy/storage/__init__.py |
Updated exports to include pack-related classes and functions |
tests/storage/test_*.py |
5 comprehensive test files with 1,693 lines covering all pack functionality |
docs/concepts/*.md |
3 detailed concept guides explaining pack files, delta compression, and pack indexes |
docs/api/pack.md |
Complete API reference for pack-related modules |
mkdocs.yml |
Updated navigation to include new documentation pages |
uv.lock |
Version bump from 0.2.0 to 0.2.1 |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…lain CLI)
Complete the remaining gitpy implementation phases tracked in
docs/design/implementation_agents.md, building on the Phase 1-2b
object model, storage, and pack support.
- refs: HEAD (attached/detached), branches, tags (lightweight +
annotated), reflog, revision parsing (HEAD^, ~N, ^N, ^0, @{N},
abbreviated SHAs), packed-refs, atomic locked writes with name
validation (gitpy/refs/)
- index: Git index v2 binary format, (path, stage) conflict keying,
read_tree/write_tree, status detection, UTF-8 byte-length flags,
mode/ctime-aware stat comparison (gitpy/index/)
- diff: minimal Myers algorithm, unified hunk formatting, tree diff,
binary detection (gitpy/diff/)
- commands: plumbing (hash-object, cat-file, ls-tree, write-tree,
commit-tree, update-ref) and porcelain (init, add, commit, status,
log, diff, branch, checkout) as framework-agnostic functions, wired
through a 14-command Typer CLI (gitpy/commands/, gitpy/cli.py)
- config: minimal .git/config reader for user.name/email (gitpy/config.py)
- repository: lazy accessors for refs/head/branches/tags/reflog/index/config
- storage: chained REF_DELTA resolution, COPY-op splitting at 0xFFFFFF,
public resolve_short_sha API
Hardened against path traversal in checkout and ref writes, correct
symlink/exec-mode handling, and byte-for-byte Git compatibility
(verified against real Git via bidirectional interop tests).
602 tests pass; ruff, mypy strict, and bandit clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The published mkdocs site previously covered only Phases 1-2b. Bring it up to date with the shipped codebase (Phases 1-8 + 14-command CLI). - usage/cli.md: reference for all 14 commands with examples - concepts: references, index & staging area, Myers/unified/tree diff - api: refs, index (staging), diff, and config module references - README: replace stale black badge with Ruff; fill in Usage section - mkdocs.yml: add Usage section and nav entries for the new pages All documented commands and APIs verified against the code; mkdocs build passes with --strict (zero published-page warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
pip-audit (CI "Check vulnerability" step) flagged 13 CVEs across 9 packages. Bump only the affected transitive/dev dependencies to their fixed versions, leaving the toolchain (mypy, ruff, typer, rich) pinned: filelock 3.20.2->3.29.0, idna 3.11->3.17, pip 25.3->26.1.2, pygments 2.19.2->2.20.0, pymdown-extensions 10.20->10.21.3, pytest 9.0.2->9.0.3, requests 2.32.5->2.34.2, urllib3 2.6.2->2.7.0, virtualenv 20.35.4->21.4.2 pip-audit now reports no known vulnerabilities; ruff, mypy strict, bandit clean; 602 tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
GitHub flagged actions/checkout@v4, actions/setup-python@v5, and astral-sh/setup-uv@v4 as running on the deprecated Node.js 20 runtime (forced to Node 24 on 2026-06-16). Bump to current Node-24 majors: actions/checkout@v4 -> v6 actions/setup-python@v5 -> v6 astral-sh/setup-uv@v4 -> v7 setup-uv v8 has no floating major tag yet, so pin its latest moving major (v7, also Node 24). peaceiris/actions-gh-pages@v4 and commitizen-action@master were not flagged and are left unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
71dd4b8 to
c3ce158
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Types of changes
Description
Checklist:
uv run inv stylelocally to ensure all linter checks passuv run inv testlocally to ensure all test cases passuv run inv securelocally to ensure no major vulnerability is introducedSteps to Test This Pull Request
Expected behavior
Related Issue
Additional context