00. 项目概述

python-git-reproduction 是一个使用纯 Python 3 复现 Git 的工程。项目运行后在工作区生成 .pygit 目录，并通过 Python 代码实现 Git 的对象存储、索引、引用、分支、提交、合并、打包、远端同步等能力。

最终目标

最终目标是复现 Git 的完整核心功能，并尽量让 .pygit 中生成的对象、索引、引用和 packfile 能被官方 Git 客户端识别。

这里的“完整”不是一次性完成所有复杂边界，而是作为长期目标分阶段推进：先实现对象库和本地提交闭环，再实现分支、状态、重置和标签，然后实现合并、stash、packfile 和远端通信。

兼容性原则

• 对象格式必须遵循 Git 标准：[type] [size]\x00[content]。
• 松散对象必须使用 SHA-1 内容寻址，并以 objects/xx/yyyy... 形式存储。
• 索引文件必须以 Git Index V2 为目标格式。
• 引用文件必须使用文本 SHA-1 或符号引用格式。
• packfile 和 idx 文件必须以 Git Pack Version 2 为目标。

非目标

项目不追求复刻 Git 的 C 语言实现结构，也不追求第一阶段覆盖 Git 的所有历史兼容包袱。实现应以“格式兼容、行为可解释、代码可测试”为优先级。

项目明确不实现 Git LFS。大文件仍按普通 Git blob、tree、commit 和 packfile 路线处理，可以做流式读取、压缩和 packfile 优化，但不引入 LFS pointer、LFS 对象目录、clean/smudge filter、LFS batch API 或 LFS 远端传输协议。

代码风格硬性要求

所有 Python 代码必须提供全面中文注释。文件开头要说明实现意图；函数要说明职责、参数、返回值和副作用；二进制格式、复杂算法、异常回滚、兼容性关键点必须写中文关键注释。