The goal of this project is to reproduce Git's core low-level logic, high-level command workflow, object storage format, index format, reference system, merge engine, packfiles, and remote synchronization capabilities in pure Python 3. The version-control directory generated by the project is named .pygit.

1. README.md: this document, the main entry point for all documents under docs/.
2. SDD_REQUIREMENTS.md: SDD engineering requirements, testing requirements, dangerous-command safety requirements, SOLID/DRY, and commit quality requirements.
3. TASKS.md: development task list and completion status; completed tasks are marked with [x].
4. PROJECT_TREE.md: recommended source layout and module responsibilities.
5. prd/00-overview.md: project goals, scope, and compatibility principles.
6. prd/01-repository-layout.md: the .pygit repository directory layout.
7. prd/02-object-database.md: the four core Git object types and the object database.
8. prd/03-index.md: the Git Index V2 binary staging area.
9. prd/04-plumbing-commands.md: low-level plumbing commands.
10. prd/05-porcelain-commands.md: high-level user commands.
11. prd/06-merge.md: branch merging and conflict handling.
12. prd/07-packfile-remote.md: packfiles, fetch, push, and clone.
13. prd/08-non-functional.md: performance, locking, validation, error handling, and unittest requirements.
14. prd/09-roadmap.md: staged implementation roadmap.

docs/
├── README.md
├── PROJECT_TREE.md
├── SDD_REQUIREMENTS.md
├── TASKS.md
└── prd/
    ├── 00-overview.md
    ├── 01-repository-layout.md
    ├── 02-object-database.md
    ├── 03-index.md
    ├── 04-plumbing-commands.md
    ├── 05-porcelain-commands.md
    ├── 06-merge.md
    ├── 07-packfile-remote.md
    ├── 08-non-functional.md
    └── 09-roadmap.md

PROJECT_TREE.md describes the recommended source layout, module responsibilities, test layout, and the Python Chinese-comment conventions.

SDD_REQUIREMENTS.md describes the engineering requirements for keeping specification, design, development, and testing aligned, and emphasizes that dangerous commands must protect the user's machine.

TASKS.md tracks the current implementation progress. The current task list has been fully completed and contains no unchecked items.

The prd/ directory stores the split product requirements documents. Each file is responsible for one topic so that a single giant PRD does not become difficult to maintain.

The current project already supports local .pygit usage, local-path remote synchronization, and a self-hosted .pygit dedicated TCP server.

Completed capabilities include:

• Local commit loop: init, add, commit, log, status.
• Plumbing commands: hash-object, cat-file, write-tree, read-tree, commit-tree, update-ref.
• Local workflow: rm, branch, checkout, switch, tag, reset, stash, merge.
• Object database: loose objects, trees, commits, tags, pack v2, idx v2, and ref-delta reading.
• Remote synchronization: local-path clone/fetch/push, plus clone/fetch/push through the dedicated pygit://host:port server.
• Safety boundaries: non-fast-forward push rejection, path checks for dangerous working-tree operations, and untracked file protection.
• Tests: 62 unittest cases, all using real temporary directories, real .pygit repositories, a real object database, a real index, and real working-tree files.

Explicitly not implemented:

• GitHub, SSH Git, HTTP Git, and the official Git wire protocol.
• Git LFS.
• The official git daemon. This project implements a .pygit dedicated server, that is, a pygit daemon.

Current final verification command:

python3 -m unittest discover -s tests -p 'test_*.py'

Current result:

Ran 62 tests

OK

The project requires tests not to replace core Git behavior with mocks. The current repository contains no use of mock, Mock, unittest.mock, MagicMock, or patch(.

• The ultimate goal must be to reproduce Git's complete core capabilities rather than to build a simplified toy system.
• The project must be as compatible as possible with official Git object formats, index formats, reference formats, and packfile formats.
• The project must strictly use the Python standard library and must not introduce third-party dependencies.
• The project must prioritize data correctness, binary-format compatibility, and repository consistency under exceptional conditions.
• The project design must follow SOLID and DRY principles: module responsibilities should be clear, repeated logic should be centralized and reused, and dangerous operations or compatibility-critical logic must not be duplicated in scattered places.
• Abstractions must serve Git semantics and testability. Design patterns must not be introduced only for form while sacrificing binary-format clarity.
• Python source files must use comprehensive Chinese comments: an intent comment at the top of each file, function-level comments for behavior, and clear Chinese explanations for complex logic, long sentences, binary layouts, boundary conditions, and key algorithms.