Git Clone

Implementing a minimalist Git-compatible version control system in Python as a learning project inspired by Write yourself a Git.

Audience: this README is tailored for the two maintainers collaborating on this repository. It documents how we work together using Gitflow while we translate the tutorial into runnable Python code.

Why this project exists

• Deepen our understanding of how Git stores data, manages history, and resolves merges by rebuilding core primitives ourselves.
• Practice disciplined collaboration using Gitflow and peer reviews from day one.
• Produce a reference-quality set of notes, docs, and code comments that explain the internals of Git in plain language.

Table of contents

1. Repository layout
2. Project roadmap
3. Environment setup
4. Documentation maintenance
5. Gitflow collaboration guide
6. GitHub project management
7. AI agent collaboration reference
8. Coding standards
9. Testing strategy
10. Reference material

Repository layout

Git-Clone/
├─ README.md               ← You are here
├─ pyproject.toml          ← Modern Python package configuration
├─ CHANGELOG.md            ← Project change history
├─ LICENSE                 ← MIT License
├─ src/
│  └─ ugit/                ← Main package directory
│     ├─ __init__.py       ← Package initialization
│     ├─ __main__.py       ← Console entry point exposed as `ugit`
│     └─ ...               ← Core implementation modules live here
└─ docs/                   ← Design notes, diagrams, references (create as needed)

Keep tutorial notes in docs/notes/ so they don't clutter feature commits.

Project roadmap

We'll follow the structure of the ugit tutorial while adapting it for our needs. Each numbered item becomes a GitHub milestone with associated issues for individual features.

1. Repository plumbing – implement init, object storage (blobs, trees, commits), and hashing.
2. Working tree commands – add status, add, and commit to mimic Git porcelain.
3. History traversal – support log, parents, and commit graphs.
4. Branches & refs – implement refs, branch, checkout, and fast-forward merges.
5. Merging & conflicts – add three-way merge logic and conflict markers.
6. Networking (stretch) – explore pushing/pulling between repos if time allows.

For each milestone:

• GitHub milestone setup: Create milestone in GitHub Issues with target completion date
• Issue breakdown: Create individual issues for each feature within the milestone
• Design first: Create a design note in docs/ summarizing the data model and CLI behavior
• Document as you go: Update docs/commands.md and CHANGELOG.md with each feature
• Capture learnings: Record open questions, deviations from the tutorial, and architectural decisions
• Demo planning: Decide upfront how we'll test and demonstrate the completed feature
• Knowledge transfer: Ensure both team members understand the implementation through clear documentation
• Milestone review: Close milestone when all issues are complete and documentation is updated

Environment setup

We both develop on Windows with Bash (Git for Windows). Target Python 3.13 to match the existing bytecode cache.

1. Clone the repo and enter the project directory.
2. (Recommended) Create and activate a virtual environment:

   python -m venv .venv
   source .venv/Scripts/activate

3. Upgrade tooling and perform an editable install from the repository root (adds the ugit console script):

   python -m pip install --upgrade pip
   python -m pip install --user -e .

   • Skip --user when working inside a virtual environment.
   • Runtime dependencies live in docs/requirements.txt; the tutorial currently needs only the Python standard library.
4. Install or update dev-time tooling via docs/requirements-dev.txt:

   python -m pip install -r docs/requirements-dev.txt

When new dependencies are introduced, record runtime packages in docs/requirements.txt and dev-only tools in docs/requirements-dev.txt, then commit both alongside the feature work.

Documentation maintenance

Our documentation-first approach ensures knowledge is captured as we learn. Here's how to maintain each file:

Core documentation files

• CHANGELOG.md: Update the [Unreleased] section for every PR. Use categories: Added, Changed, Deprecated, Removed, Fixed, Security
• docs/commands.md: Add entries for new CLI commands with usage examples and explanations
• docs/references.md: Log useful resources, tutorials, and articles as you discover them
• README.md: Update when project structure, workflow, or setup instructions change

When to update documentation

Change Type	Required Documentation Updates
New CLI command	docs/commands.md, CHANGELOG.md, docstrings, close GitHub issue
New module/package	CHANGELOG.md, code comments, design notes, update issue status
Workflow change	README.md, CHANGELOG.md, notify team via GitHub Discussions
New dependency	requirements.txt, CHANGELOG.md, document in issue
Bug fix	CHANGELOG.md, improved code comments, reference issue in commit
Tutorial deviation	Design note in docs/, CHANGELOG.md, create discussion issue

Documentation quality checklist

Before each PR, verify:

• GitHub issue linked and acceptance criteria met
• New commands are documented with examples
• CHANGELOG.md reflects all changes
• Code comments explain why, not just what
• External resources are logged in docs/references.md
• README stays current with project structure
• GitHub Projects board reflects current status

Gitflow collaboration guide

We treat main as deployable and develop as the integration branch. All feature work happens off develop. We use GitHub Projects and GitHub Issues to coordinate work and track progress.

GitHub project management

Issue-driven development

All work starts with a GitHub issue:

1. Create issues for:

   • New features from the tutorial roadmap
   • Bug reports and fixes
   • Documentation improvements
   • Technical debt and refactoring

2. Issue templates and labels:

   • feature - New functionality (tutorial milestones)
   • bug - Something that's broken
   • documentation - Docs improvements
   • good first issue - Suitable for getting started
   • milestone:X - Links to specific tutorial sections

3. GitHub Projects board:

   • Backlog: Issues we plan to work on
   • Sprint: Current iteration (usually 1-2 tutorial sections)
   • In Progress: Actively being worked on
   • Review: PRs awaiting review
   • Done: Completed and merged

Issue workflow

Idea/Bug → GitHub Issue → Feature Branch → Pull Request → Merge → Close Issue

1. Before starting work: Assign yourself to the issue and move it to "In Progress"
2. Branch naming: Include issue number: feature/42-object-storage
3. Commit messages: Reference issues: Add blob storage (#42)
4. PR linking: Use "Closes #42" in PR description to auto-close issues
5. Review process: Move PR card to "Review" column when ready

Branch naming

Type	Prefix	Example
Feature	feature/	feature/42-object-storage
Release	release/	release/v0.1.0
Hotfix	hotfix/	hotfix/15-add-commit-bug
Documentation	docs/	docs/23-readme-roadmap

Branch naming convention: <type>/<issue-number>-<short-description>

• Always include the GitHub issue number for traceability
• Use kebab-case for the description part
• Keep descriptions short but descriptive

Daily workflow

1. Start with GitHub Projects:

   • Check the project board for assigned issues in "Sprint" or "Backlog"
   • Assign yourself to an issue and move it to "In Progress"
   • Read through issue description and acceptance criteria

2. Sync and branch:

   git checkout main
   git pull origin main
   git checkout develop
   git pull origin develop
   git checkout -b feature/<issue-number>-<short-description>

3. Implement and document simultaneously:

   • Code the feature with clear docstrings
   • Update docs/commands.md for any new CLI commands
   • Add entries to CHANGELOG.md under [Unreleased]
   • Update docs/references.md if using new external resources
   • Test your changes and document any new testing approaches

4. Commit with issue references:

   git commit -m "Add blob storage implementation (#42)
   
   - Implement hash-based content storage
   - Add write_object and read_object functions
   - Update commands.md with new CLI usage"

5. Pre-PR documentation review:

   • Ensure all new commands are documented in docs/commands.md
   • Verify CHANGELOG.md has appropriate entries
   • Update README if project structure or workflow changes
   • Check that code comments explain why, not just what

6. Create pull request:

   • Push to origin and open a pull request back into develop
   • PR title: Include issue number: Add object storage implementation (#42)
   • PR description: Use template and include Closes #42
   • Move the GitHub Projects card to "Review" column

7. Review process:

   • Request review from your teammate
   • Use the PR template checklist:
     • Issue linked and acceptance criteria met
     • Feature spec or design note linked
     • Tests added/updated
     • Commands documented in docs/commands.md
     • Changes logged in CHANGELOG.md
     • README or other docs updated if needed
     • New references added to docs/references.md

8. Complete the cycle:

   • After approval, squash-merge into develop
   • Delete the remote branch
   • Issue automatically closes and moves to "Done" in Projects

Releases & hotfixes

Release preparation:

• Cut a release/x.y.z branch once develop is feature-complete
• GitHub milestone management:
  • Close the current milestone in GitHub Issues
  • Create a new milestone for the next version
  • Move any incomplete issues to the new milestone
• Documentation cleanup:
  • Move [Unreleased] changes in CHANGELOG.md to a new version section
  • Update version number in src/ugit/__init__.py
  • Review and polish docs/commands.md for completeness
  • Ensure README accurately reflects current project state
• Only allow bug fixes, docs, and metadata updates on release branches
• GitHub Release:
  • Tag releases from main after merging the release branch
  • Create a GitHub Release with changelog highlights
  • Back-merge to develop and update GitHub Projects board

Hotfixes:

• Create a GitHub issue for the hotfix with hotfix label
• Start from main, merge back into both main and develop
• Update CHANGELOG.md with hotfix details
• Create immediate patch release on GitHub with version bump

AI agent collaboration reference

This section provides guidance for AI agents helping with the gitflow process and development workflow.

Workflow troubleshooting

When branches get out of sync:

git checkout develop
git pull origin develop
git checkout feature/branch-name
git rebase develop  # or git merge develop

When GitHub Projects board is stale:

• Check issue status matches actual progress
• Move cards to reflect current reality
• Update issue descriptions if scope changed

When main/develop diverge unexpectedly:

• Check if hotfix was applied only to main
• Create issue for back-merge: hotfix: sync develop with main
• Follow hotfix procedure in releases section

AI agent decision tree

For feature work:

1. ✅ Check if GitHub issue exists → if not, create one
2. ✅ Follow branch naming with issue number
3. ✅ Update documentation in same commit when possible
4. ✅ Reference issue number in commits

For bug fixes:

1. ✅ Determine severity: hotfix (main) vs normal (develop)
2. ✅ Create issue if none exists
3. ✅ Follow appropriate branch strategy
4. ✅ Update CHANGELOG.md

For documentation:

1. ✅ Assess scope: full issue vs docs branch vs piggyback
2. ✅ Choose appropriate method from options above
3. ✅ Always update CHANGELOG.md for substantial changes

Emergency procedures

If develop is broken:

• Create hotfix branch from last known good commit
• Fix issue and test thoroughly
• Create emergency PR with teammate notification

If main deployment fails:

• Immediately create hotfix branch from main
• Apply minimal fix and thorough testing
• Coordinate with team for rapid review

If GitHub Projects becomes unreliable:

• Fall back to git branch/commit tracking
• Document current state in issue comments
• Schedule cleanup when Projects is restored

Coding standards

• Structure: group implementation modules under src/ugit/ as they materialize. The main CLI lives in src/ugit/__main__.py and follows proper Python package structure.
• Documentation-first development:
  • Commands: every new command gets a docstring and a corresponding section in docs/commands.md with usage examples
  • Code comments: explain why decisions were made, not just what the code does
  • Tutorial references: link commits to tutorial sections (e.g., Section 2.3 – Implement add)
  • Design notes: capture architectural decisions and deviations from the tutorial in docs/
• Change tracking:
  • CHANGELOG.md: update the [Unreleased] section for every feature, bugfix, or breaking change
  • References: add new learning resources to docs/references.md as you discover them
  • Version bumps: follow semantic versioning and update version in src/ugit/__init__.py
• Commit discipline:
  • Reference tutorial sections or issues (e.g., Section 2.3 – Implement add)
  • Include documentation updates in the same commit as the feature when possible
  • Write commit messages that explain the why behind changes

Testing strategy

• Unit tests with pytest covering each command's behavior.

Reference material

In docs/references.md.