fromscratch-pygit 0.3.0__py3-none-any.whl

fromscratch_pygit-0.3.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: fromscratch-pygit
+Version: 0.3.0
+Summary: An educational version control system built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pygit
+Project-URL: Repository, https://github.com/robcox2910/pygit
+Project-URL: Issues, https://github.com/robcox2910/pygit/issues
+Project-URL: Documentation, https://robcox2910.github.io/pygit/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: education,git,learning,version-control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyGit
+
+**Build your own version control system from scratch!**
+
+PyGit is a simplified version of Git, written entirely in Python. It teaches
+you how version control really works under the hood -- hashing, blobs, trees,
+commits, branches, and diffs -- by building each piece yourself.
+
+## What is version control?
+
+Imagine you are writing a story. Every time you finish a chapter, you save a
+copy so you can go back to it later. Version control does the same thing for
+code -- it remembers every change you make, who made it, and why.
+
+## Quick start
+
+```python
+from pygit.repository import Repository
+
+# Create a new repository
+repo = Repository.init("my-project")
+
+# Create a file and stage it
+with open("my-project/hello.txt", "w") as f:
+    f.write("Hello, world!")
+
+repo.add("hello.txt")
+
+# Commit the change
+commit_hash = repo.commit("Add greeting")
+print(f"Created commit: {commit_hash}")
+
+# Make another change
+with open("my-project/hello.txt", "w") as f:
+    f.write("Hello, everyone!")
+
+repo.add("hello.txt")
+repo.commit("Update greeting")
+
+# See the history
+for entry in repo.log():
+    print(f"{entry.commit_hash[:8]} {entry.message}")
+```
+
+## Features
+
+- **Hashing** -- Every piece of content gets a unique fingerprint using SHA-1,
+  with Git's `blob <size>` label in front -- so file (blob) hashes match
+  `git hash-object` exactly. (Trees and commits use a simpler JSON layout than
+  real Git, so their hashes differ.)
+- **Nested trees** -- Every folder gets its own tree, just like real Git.
+- **Object store** -- Files are stored by their hash, so identical content is
+  never duplicated.
+- **Trees** -- Snapshots of your directory structure, like a table of contents.
+- **Commits** -- Diary entries that record what changed, when, and why. Each
+  commit points to its parent, forming a chain of history.
+- **Branches** -- Create parallel timelines to work on different ideas without
+  affecting the main project.
+- **Staging area** -- Choose exactly which changes go into the next commit.
+- **Diff** -- Compare two versions of a file to see what was added or removed.
+- **Status** -- See what files are staged and ready to commit.
+
+## Installation
+
+```bash
+uv sync --all-extras
+```
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+## Project structure
+
+```
+src/pygit/
+    __init__.py      -- Package marker
+    hashing.py       -- SHA-1 fingerprinting
+    objects.py       -- Content-addressed object store
+    tree.py          -- Directory snapshots
+    commit.py        -- History entries
+    diff.py          -- Line-by-line comparison
+    repository.py    -- Ties everything together
+    errors.py        -- Custom exceptions
+```
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| **PyGit** | **Version control** | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pygit/
+<!-- docs:end -->
+
+## License
+
+MIT

fromscratch_pygit-0.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pygit/__init__.py,sha256=xS83fE7qID3qyidvXkbURqbBpqkpJCp7_crYu_LIemI,83
+pygit/_version.py,sha256=RCY04NY0kBCyn6ttH6lnVL6Gz2gceOrt45f0yDOOU8A,520
+pygit/cli.py,sha256=r6NrBkPJ-KuB-IA3t-KoyUmLBeKRssO4icPDYYCRhKY,3922
+pygit/commit.py,sha256=CPFqbRRjXRykgNH6pcwf8wLbOS-8jaj_vsD8N0z6wdQ,2380
+pygit/diff.py,sha256=DVrYUFj_TwsgOXo2Gl9OM5pdeZO1cAcIbV2ULWTjbIM,2366
+pygit/errors.py,sha256=JRMCi7FKVFoMYjQeh8vYPj9r4RNpEStS03TjS23t1uY,531
+pygit/hashing.py,sha256=A1e4FlpsXaDqdZfptV2vDTMqNIrmYCP-zdDMurogfgM,1665
+pygit/objects.py,sha256=U-7lieBHYe8wXAOX3fywUglTUEF27KZBoynJPDaZPqY,4116
+pygit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygit/repository.py,sha256=uNeAfnXw8lPeIhojlTmisy0pUeC_AXeHOo-QSftY0e0,14083
+pygit/tree.py,sha256=7wH8nuVYDFVT0sF0zr6kyFRwiR5dV1a7EJB9rpQU9ik,1696
+fromscratch_pygit-0.3.0.dist-info/METADATA,sha256=qqbc7WLrpE-8nQLz45HJplxqyFJ42RL4zHUHxI0nPz4,7396
+fromscratch_pygit-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pygit-0.3.0.dist-info/entry_points.txt,sha256=GDL2QmULHR1NnRsbzAIxB019nLk_chDr54Tx2qS2ZLw,41
+fromscratch_pygit-0.3.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pygit-0.3.0.dist-info/RECORD,,

fromscratch_pygit-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromscratch_pygit-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pygit = pygit.cli:main

fromscratch_pygit-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygit/__init__.py

@@ -0,0 +1 @@
+"""PyGit -- an educational version control system built from scratch in Python."""

pygit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

pygit/cli.py

@@ -0,0 +1,127 @@
+"""Command line -- the control panel for PyGit.
+
+Like the row of buttons on a machine, this lets you drive PyGit from
+your terminal: press a button (type a command) and PyGit does the work.
+It wires the ``pygit`` command to the :class:`~pygit.repository.Repository`
+so you can init, add, commit, log, and check status without writing any
+Python.
+"""
+
+import argparse
+import sys
+
+from pygit.errors import PyGitError
+from pygit.repository import Repository
+
+SHORT_HASH_LENGTH = 8
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    """Create a new repository in the given directory."""
+    repo = Repository.init(args.path)
+    print(f"Initialized empty pygit repository in {repo.path}")
+    return 0
+
+
+def _cmd_add(args: argparse.Namespace) -> int:
+    """Stage a file for the next commit."""
+    repo = Repository(args.path)
+    blob_hash = repo.add(args.file)
+    print(f"Staged {args.file} ({blob_hash[:SHORT_HASH_LENGTH]})")
+    return 0
+
+
+def _cmd_commit(args: argparse.Namespace) -> int:
+    """Record the staged files as a new commit."""
+    repo = Repository(args.path)
+    commit_hash = repo.commit(args.message, author=args.author)
+    print(f"[{repo.current_branch()} {commit_hash[:SHORT_HASH_LENGTH]}] {args.message}")
+    return 0
+
+
+def _cmd_log(args: argparse.Namespace) -> int:
+    """Print the commit history, newest first."""
+    repo = Repository(args.path)
+    for commit in repo.log():
+        print(f"commit {commit.commit_hash}")
+        print(f"Author: {commit.author}")
+        print(f"Date:   {commit.timestamp}")
+        print(f"\n    {commit.message}\n")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    """Print the files currently staged for commit."""
+    repo = Repository(args.path)
+    staged = repo.status()
+    if not staged:
+        print("Nothing staged for commit.")
+        return 0
+    print("Staged files:")
+    for name in sorted(staged):
+        print(f"  {name}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="pygit",
+        description="A tiny version control system built from scratch.",
+    )
+    parser.add_argument(
+        "-C",
+        dest="path",
+        default=".",
+        help="Run as if pygit was started in this directory.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Create a new repository.")
+    init_parser.set_defaults(func=_cmd_init)
+
+    add_parser = subparsers.add_parser("add", help="Stage a file for the next commit.")
+    add_parser.add_argument("file", help="Path to the file to stage.")
+    add_parser.set_defaults(func=_cmd_add)
+
+    commit_parser = subparsers.add_parser("commit", help="Record staged changes.")
+    commit_parser.add_argument("-m", "--message", required=True, help="The commit message.")
+    commit_parser.add_argument("--author", default="Anonymous", help="The author's name.")
+    commit_parser.set_defaults(func=_cmd_commit)
+
+    log_parser = subparsers.add_parser("log", help="Show the commit history.")
+    log_parser.set_defaults(func=_cmd_log)
+
+    status_parser = subparsers.add_parser("status", help="Show staged files.")
+    status_parser.set_defaults(func=_cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the ``pygit`` command-line tool.
+
+    Args:
+        argv: The command-line arguments (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        A process exit code: 0 on success, 1 on error.
+
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    try:
+        result: int = args.func(args)
+    except PyGitError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return result
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pygit/commit.py

@@ -0,0 +1,87 @@
+"""Commits -- diary entries for your project.
+
+A commit records a moment in time: what the project looked like (the
+tree), who made the change (the author), when it happened (the
+timestamp), and why (the message). Each commit points back to its
+parent, forming a chain of history.
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from pygit.hashing import hash_object
+
+
+@dataclass(frozen=True, slots=True)
+class Commit:
+    """A snapshot of the project at a moment in time.
+
+    Args:
+        tree_hash: The hash of the tree representing the project state.
+        parent_hash: The hash of the previous commit (None for first commit).
+        author: Who made this commit.
+        timestamp: When this commit was made.
+        message: Why this commit was made.
+        commit_hash: The hash of this commit itself.
+
+    """
+
+    tree_hash: str
+    parent_hash: str | None
+    author: str
+    timestamp: str
+    message: str
+    commit_hash: str
+
+
+def create_commit(
+    tree_hash: str,
+    parent_hash: str | None,
+    message: str,
+    author: str = "Anonymous",
+) -> tuple[str, str]:
+    """Create a new commit object.
+
+    Args:
+        tree_hash: The hash of the root tree.
+        parent_hash: The hash of the parent commit (None for first).
+        message: The commit message.
+        author: The author's name.
+
+    Returns:
+        A tuple of (commit_hash, serialized_commit_content).
+
+    """
+    timestamp = datetime.now(tz=UTC).isoformat()
+    data = {
+        "tree": tree_hash,
+        "parent": parent_hash,
+        "author": author,
+        "timestamp": timestamp,
+        "message": message,
+    }
+    content = json.dumps(data)
+    commit_hash = hash_object("commit", content.encode())
+    return commit_hash, content
+
+
+def parse_commit(content: str) -> Commit:
+    """Deserialize a commit from its stored content.
+
+    Args:
+        content: The JSON-serialized commit content.
+
+    Returns:
+        A Commit object.
+
+    """
+    data: dict[str, str | None] = json.loads(content)
+    return Commit(
+        tree_hash=str(data["tree"]),
+        parent_hash=str(data["parent"]) if data.get("parent") else None,
+        author=str(data.get("author", "Unknown")),
+        timestamp=str(data.get("timestamp", "")),
+        message=str(data.get("message", "")),
+        commit_hash=hash_object("commit", content.encode()),
+    )

pygit/diff.py

@@ -0,0 +1,79 @@
+"""Diff -- spot the differences between two versions.
+
+A diff compares two strings line by line and shows what was added,
+removed, or unchanged. Lines starting with `+` were added, lines
+starting with `-` were removed, and lines with a two-space prefix are
+unchanged.
+
+This is a simple educational diff -- real Git uses more sophisticated
+algorithms (like Myers diff) for better results on large files.
+"""
+
+
+def diff_lines(old: str, new: str) -> list[str]:
+    """Compare two strings line by line and return a diff.
+
+    Walks both texts once from top to bottom with a greedy scan: when
+    the current lines match they are kept as unchanged; otherwise the
+    line that is missing from the other side is marked removed or added.
+    This is simpler (and less precise) than the longest-common-
+    subsequence algorithms real diff tools use.
+
+    Args:
+        old: The original text.
+        new: The modified text.
+
+    Returns:
+        A list of diff lines, each prefixed with "+", "-", or " ".
+
+    """
+    old_lines = old.splitlines()
+    new_lines = new.splitlines()
+
+    # Build a set for quick membership tests.
+    old_set = set(old_lines)
+    new_set = set(new_lines)
+
+    result: list[str] = []
+    old_idx = 0
+    new_idx = 0
+
+    while old_idx < len(old_lines) and new_idx < len(new_lines):
+        if old_lines[old_idx] == new_lines[new_idx]:
+            result.append(f"  {old_lines[old_idx]}")
+            old_idx += 1
+            new_idx += 1
+        elif old_lines[old_idx] not in new_set:
+            result.append(f"- {old_lines[old_idx]}")
+            old_idx += 1
+        elif new_lines[new_idx] not in old_set:
+            result.append(f"+ {new_lines[new_idx]}")
+            new_idx += 1
+        else:
+            result.append(f"- {old_lines[old_idx]}")
+            old_idx += 1
+
+    # Remaining old lines were removed.
+    while old_idx < len(old_lines):
+        result.append(f"- {old_lines[old_idx]}")
+        old_idx += 1
+
+    # Remaining new lines were added.
+    while new_idx < len(new_lines):
+        result.append(f"+ {new_lines[new_idx]}")
+        new_idx += 1
+
+    return result
+
+
+def format_diff(diff: list[str]) -> str:
+    """Format a diff as a single string for display.
+
+    Args:
+        diff: The list of diff lines from ``diff_lines()``.
+
+    Returns:
+        A newline-joined string.
+
+    """
+    return "\n".join(diff)

pygit/errors.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for PyGit.
+
+Clear error messages help you understand what went wrong. Each
+exception type tells you the category of the problem.
+"""
+
+
+class PyGitError(Exception):
+    """Base exception for all PyGit errors."""
+
+
+class ObjectNotFoundError(PyGitError):
+    """Raise when a requested object hash doesn't exist."""
+
+
+class RepositoryError(PyGitError):
+    """Raise when a repository operation fails."""
+
+
+class ObjectTypeError(PyGitError):
+    """Raise when an object's type label isn't the type we asked for."""

pygit/hashing.py

@@ -0,0 +1,50 @@
+"""Hashing -- fingerprints for content.
+
+Every piece of content gets a unique fingerprint (hash). The same
+content always gets the same fingerprint. Different content gets
+different fingerprints. This is the foundation of everything in Git.
+
+We use SHA-1 (like real Git) to produce 40-character hex strings.
+
+Before taking the fingerprint, Git sticks a little **label** on the
+front saying what kind of object it is and how big it is -- for a file
+saying ``hello``, the label is ``blob 6`` followed by a zero byte. We do
+exactly the same, which means:
+
+- a file and a tree can never get the same fingerprint by accident, even
+  if their bytes happen to match (the labels differ), and
+- our file (blob) fingerprints are *identical* to real Git's -- try
+  ``git hash-object`` on the same file!
+"""
+
+import hashlib
+
+HASH_LENGTH = 40
+
+
+def object_header(object_type: str, data: bytes) -> bytes:
+    r"""Make the label Git puts in front of every object: ``<type> <size>`` and a zero byte.
+
+    Args:
+        object_type: What kind of object this is ("blob", "tree" or "commit").
+        data: The object's content.
+
+    Returns:
+        The header bytes, for example ``b"blob 6\x00"``.
+
+    """
+    return f"{object_type} {len(data)}\0".encode()
+
+
+def hash_object(object_type: str, data: bytes) -> str:
+    """Take the fingerprint of an object: SHA-1 of its label plus its content.
+
+    Args:
+        object_type: What kind of object this is ("blob", "tree" or "commit").
+        data: The object's content.
+
+    Returns:
+        A 40-character hexadecimal hash string.
+
+    """
+    return hashlib.sha1(object_header(object_type, data) + data).hexdigest()  # noqa: S324

pygit/objects.py

@@ -0,0 +1,110 @@
+"""Object store -- the photo album for blobs, trees, and commits.
+
+Git stores everything as "objects" identified by their hash. This
+module handles reading and writing those objects to disk. Objects
+are stored in `.pygit/objects/` using the first two characters of
+the hash as a subdirectory name (to avoid one huge folder).
+
+Example:
+    Hash: 943a702d06f34599aee1f8da8ef9f7296031d699
+    Path: .pygit/objects/94/3a702d06f34599aee1f8da8ef9f7296031d699
+
+Each object file holds a small label -- its type and size, like
+``blob 13`` and a zero byte -- followed by the content, exactly as real
+Git does. (Real Git also squashes the file with zlib compression; we
+skip that so you can open the files and look inside.)
+
+"""
+
+from pathlib import Path
+
+from pygit.errors import ObjectNotFoundError, ObjectTypeError
+from pygit.hashing import hash_object, object_header
+
+PREFIX_LENGTH = 2
+
+
+class ObjectStore:
+    """Read and write content-addressed objects.
+
+    Each object is stored as a file named by its hash, inside a
+    subdirectory named by the first two characters of the hash.
+
+    Args:
+        objects_dir: Path to the `.pygit/objects` directory.
+
+    """
+
+    __slots__ = ("_objects_dir",)
+
+    def __init__(self, objects_dir: str | Path) -> None:
+        """Create an object store at the given path."""
+        self._objects_dir = Path(objects_dir)
+        self._objects_dir.mkdir(parents=True, exist_ok=True)
+
+    def _object_path(self, object_hash: str) -> Path:
+        """Return the filesystem path for an object hash."""
+        prefix = object_hash[:PREFIX_LENGTH]
+        rest = object_hash[PREFIX_LENGTH:]
+        return self._objects_dir / prefix / rest
+
+    def write_object(self, object_type: str, data: bytes) -> str:
+        """Store an object and return its hash.
+
+        Think of it like filing a photo in an album -- once it's
+        filed under its label (hash), you can always find it again.
+        Works for any object type: blobs, trees, or commits.
+
+        If the object already exists (same type and content), this is a
+        no-op (content-addressable means no duplicates).
+
+        Args:
+            object_type: What kind of object this is ("blob", "tree" or "commit").
+            data: The object's content.
+
+        Returns:
+            The SHA-1 hash of the labelled object.
+
+        """
+        object_hash = hash_object(object_type, data)
+        path = self._object_path(object_hash)
+        if not path.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(object_header(object_type, data) + data)
+        return object_hash
+
+    def read_object(self, object_hash: str, object_type: str) -> bytes:
+        """Retrieve an object's content by its hash, checking its type label.
+
+        Like looking up a photo in the album by its label -- hand over the
+        hash and the kind of thing you expect, and get back its content.
+
+        Args:
+            object_hash: The SHA-1 hash of the object.
+            object_type: The type you expect ("blob", "tree" or "commit").
+
+        Returns:
+            The object's content, without its label.
+
+        Raises:
+            ObjectNotFoundError: If no object with that hash exists.
+            ObjectTypeError: If the object is labelled with a different type
+                (or its label is damaged).
+
+        """
+        path = self._object_path(object_hash)
+        if not path.exists():
+            msg = f"Object not found: {object_hash}"
+            raise ObjectNotFoundError(msg)
+        header, _, data = path.read_bytes().partition(b"\0")
+        # Compare the label as bytes: a damaged file's label may not be text.
+        stored_type = header.split(b" ", 1)[0]
+        if stored_type != object_type.encode():
+            label = stored_type.decode(errors="replace")
+            msg = f"Object {object_hash} is a {label}, not a {object_type}"
+            raise ObjectTypeError(msg)
+        return data
+
+    def exists(self, object_hash: str) -> bool:
+        """Check whether an object with the given hash exists."""
+        return self._object_path(object_hash).exists()

pygit/repository.py

@@ -0,0 +1,394 @@
+"""Repository -- the diary that holds everything.
+
+The repository is the `.pygit` folder in your project. It stores all
+objects (blobs, trees, commits), tracks branches, and maintains the
+staging area. This module ties everything together.
+"""
+
+import json
+import unicodedata
+from pathlib import Path
+
+from pygit.commit import Commit, create_commit, parse_commit
+from pygit.errors import RepositoryError
+from pygit.objects import ObjectStore
+from pygit.tree import TreeEntry, build_tree, parse_tree
+
+PYGIT_DIR = ".pygit"
+OBJECTS_DIR = "objects"
+REFS_DIR = "refs/heads"
+HEAD_FILE = "HEAD"
+INDEX_FILE = "index"
+DEFAULT_BRANCH = "main"
+# Most file systems refuse a file name longer than 255 bytes.
+MAX_BRANCH_NAME_BYTES = 255
+
+
+def _check_branch_name(name: str) -> None:
+    r"""Refuse a branch name that isn't one plain, visible file name.
+
+    A branch is a file in ``.pygit/refs/heads``, named after the branch, so
+    the name must be safe to use as a file name there: not empty, not ``.``
+    or ``..``, no ``/`` or ``\`` (they would reach into other folders), no
+    spaces or invisible characters (HEAD is a line of text, and they get
+    lost), and short enough for the file system.
+
+    Raises:
+        RepositoryError: If the name isn't allowed.
+
+    """
+    if (
+        name in {"", ".", ".."}
+        or "/" in name
+        or "\\" in name
+        or not name.isprintable()
+        or any(char.isspace() for char in name)
+        or len(name.encode()) > MAX_BRANCH_NAME_BYTES
+    ):
+        msg = f"Invalid branch name: {name!r}"
+        raise RepositoryError(msg)
+
+
+def _same_name_key(name: str) -> str:
+    """Return a name as a Mac compares file names: ignoring capitals and how accents are spelled.
+
+    (Windows ignores capitals too, but not accent spelling. Folding both here
+    means PyGit refuses the same names on every computer.)
+    """
+    return unicodedata.normalize("NFD", unicodedata.normalize("NFD", name).casefold())
+
+
+class Repository:
+    """A PyGit repository -- your project's diary.
+
+    Like a diary that keeps every version of your story, the repository
+    remembers all your project's snapshots, tracks its branches, and
+    holds the staging area where you gather changes. It ties everything
+    together and manages the complete version control lifecycle: init,
+    add, commit, log, branch, and status.
+
+    """
+
+    __slots__ = ("_path", "_pygit_dir", "_store")
+
+    def __init__(self, path: str | Path) -> None:
+        """Open an existing repository.
+
+        Args:
+            path: The project root directory.
+
+        Raises:
+            RepositoryError: If no `.pygit` directory exists.
+
+        """
+        self._path = Path(path).resolve()
+        self._pygit_dir = self._path / PYGIT_DIR
+        if not self._pygit_dir.exists():
+            msg = f"Not a pygit repository: {self._path}"
+            raise RepositoryError(msg)
+        self._store = ObjectStore(self._pygit_dir / OBJECTS_DIR)
+
+    @classmethod
+    def init(cls, path: str | Path) -> Repository:
+        """Create a new repository in the given directory.
+
+        Creates the `.pygit` directory structure with objects, refs,
+        HEAD, and an empty index.
+
+        Args:
+            path: The project root directory.
+
+        Returns:
+            The newly created Repository.
+
+        """
+        root = Path(path).resolve()
+        pygit_dir = root / PYGIT_DIR
+
+        if pygit_dir.exists():
+            msg = f"Repository already exists: {root}"
+            raise RepositoryError(msg)
+
+        # Create directory structure.
+        (pygit_dir / OBJECTS_DIR).mkdir(parents=True)
+        (pygit_dir / REFS_DIR).mkdir(parents=True)
+
+        # Create HEAD pointing to main.
+        (pygit_dir / HEAD_FILE).write_text(f"ref: {REFS_DIR}/{DEFAULT_BRANCH}\n", encoding="utf-8")
+
+        # Create empty index.
+        (pygit_dir / INDEX_FILE).write_text("{}", encoding="utf-8")
+
+        return cls(root)
+
+    @property
+    def path(self) -> Path:
+        """Return the project root path."""
+        return self._path
+
+    def add(self, file_path: str) -> str:
+        """Stage a file for the next commit.
+
+        Read the file's content, store it as a blob, and record it
+        in the index (staging area).
+
+        Args:
+            file_path: Path to the file (relative to project root).
+
+        Returns:
+            The blob hash of the staged file.
+
+        Raises:
+            RepositoryError: If the file doesn't exist.
+
+        """
+        full_path = self._path / file_path
+        if not full_path.is_file():
+            msg = f"File not found: {file_path}"
+            raise RepositoryError(msg)
+
+        # Files are stored as raw bytes, so pictures and other non-text
+        # files work too.
+        blob_hash = self._store.write_object("blob", full_path.read_bytes())
+
+        # Update the index.
+        index = self._read_index()
+        index[Path(file_path).as_posix()] = blob_hash  # "./src/a.py" -> "src/a.py"
+        self._write_index(index)
+
+        return blob_hash
+
+    def commit(self, message: str, author: str = "Anonymous") -> str:
+        """Create a commit from the current staging area.
+
+        A commit is a *full snapshot*, like a photo of every room in
+        the house -- not just the room you tidied. So we start from the
+        parent commit's snapshot and lay the staged changes on top,
+        which means files committed earlier stay in the picture. Then
+        we create a commit pointing to the new tree, update the current
+        branch, and clear the index.
+
+        Args:
+            message: The commit message.
+            author: The author's name.
+
+        Returns:
+            The commit hash.
+
+        Raises:
+            RepositoryError: If the staging area is empty.
+
+        """
+        index = self._read_index()
+        if not index:
+            msg = "Nothing to commit (staging area is empty)"
+            raise RepositoryError(msg)
+
+        # Get the parent commit (current branch tip).
+        parent_hash = self._get_branch_tip()
+
+        # Start from the parent's snapshot, then overlay the staged
+        # changes so previously committed files are not lost.
+        snapshot = self._parent_tree_entries(parent_hash)
+        snapshot.update(index)
+
+        # Build a tree for every folder, from the full snapshot.
+        tree_hash = self._write_tree(snapshot)
+
+        # Create the commit.
+        commit_hash, commit_content = create_commit(
+            tree_hash=tree_hash,
+            parent_hash=parent_hash,
+            message=message,
+            author=author,
+        )
+        self._store.write_object("commit", commit_content.encode())
+
+        # Update the current branch to point to the new commit.
+        self._set_branch_tip(commit_hash)
+
+        # Clear the index.
+        self._write_index({})
+
+        return commit_hash
+
+    def log(self) -> list[Commit]:
+        """Return the commit history, newest first.
+
+        Walk the parent chain from the current branch tip back to
+        the first commit.
+
+        Returns:
+            A list of Commit objects, newest first.
+
+        """
+        commits: list[Commit] = []
+        current_hash = self._get_branch_tip()
+
+        while current_hash:
+            content = self._store.read_object(current_hash, "commit").decode()
+            commit = parse_commit(content)
+            commits.append(commit)
+            current_hash = commit.parent_hash
+
+        return commits
+
+    def status(self) -> dict[str, str]:
+        """Return the current staging area contents.
+
+        Returns:
+            A dict mapping file paths to blob hashes.
+
+        """
+        return self._read_index()
+
+    def create_branch(self, name: str) -> None:
+        """Create a new branch pointing to the current commit.
+
+        Args:
+            name: The branch name.
+
+        Raises:
+            RepositoryError: If the name isn't allowed, or the branch already
+                exists, or another branch has the same name in different
+                capitals or a different spelling of an accent (on a Mac or
+                Windows they would share one file).
+
+        """
+        _check_branch_name(name)
+        existing = self.list_branches()
+        if name in existing:
+            msg = f"Branch already exists: {name}"
+            raise RepositoryError(msg)
+        for other in sorted({*existing, self.current_branch()}):
+            if other != name and _same_name_key(other) == _same_name_key(name):
+                msg = f"Branch {name!r} differs from {other!r} only in capitals or accents"
+                raise RepositoryError(msg)
+        tip = self._get_branch_tip()
+        try:
+            (self._pygit_dir / REFS_DIR / name).write_text(tip or "", encoding="utf-8")
+        except OSError as exc:  # e.g. a Mac refuses letters newer than it knows
+            msg = f"Invalid branch name: {name!r} ({exc.strerror})"
+            raise RepositoryError(msg) from exc
+
+    def list_branches(self) -> list[str]:
+        """Return all branch names."""
+        refs_dir = self._pygit_dir / REFS_DIR
+        return sorted(p.name for p in refs_dir.iterdir() if p.is_file())
+
+    def current_branch(self) -> str:
+        """Return the name of the current branch.
+
+        Raises:
+            RepositoryError: If HEAD names something that isn't a valid
+                branch, such as a hand-edited ``ref: refs/heads/../../x``.
+
+        """
+        head = (self._pygit_dir / HEAD_FILE).read_text(encoding="utf-8").strip()
+        name = head.removeprefix(f"ref: {REFS_DIR}/")
+        # HEAD is a file anyone can edit, so check it the way a new name is
+        # checked: otherwise the next commit could write anywhere.
+        try:
+            _check_branch_name(name)
+        except RepositoryError as exc:
+            msg = f"HEAD is damaged: {head!r}"
+            raise RepositoryError(msg) from exc
+        return name
+
+    def switch_branch(self, name: str) -> None:
+        """Switch to a different branch.
+
+        Note: this only moves HEAD to point at the branch -- it does
+        not yet update the files in your working directory to match that
+        branch's snapshot (a real ``checkout``). Restoring files on
+        switch is a great exercise to try yourself!
+
+        Args:
+            name: The branch name to switch to.
+
+        Raises:
+            RepositoryError: If the name isn't allowed, or the branch doesn't exist.
+
+        """
+        _check_branch_name(name)
+        # Look for the exact name in the list: asking the file system would
+        # let "MAIN" find "main" on a Mac.
+        if name not in self.list_branches():
+            msg = f"Branch not found: {name}"
+            raise RepositoryError(msg)
+        (self._pygit_dir / HEAD_FILE).write_text(f"ref: {REFS_DIR}/{name}\n", encoding="utf-8")
+
+    # -- Internal helpers --
+
+    def _parent_tree_entries(self, parent_hash: str | None) -> dict[str, str]:
+        """Return a commit's snapshot as a mapping of file path to blob hash."""
+        if parent_hash is None:
+            return {}
+        parent = parse_commit(self._store.read_object(parent_hash, "commit").decode())
+        return self._read_tree(parent.tree_hash)
+
+    def _write_tree(self, files: dict[str, str]) -> str:
+        """Store a tree for a folder (and, inside it, one for every sub-folder).
+
+        ``files`` maps paths like ``"src/lib/util.py"`` to blob hashes. Files
+        directly in this folder become blob entries; everything under a
+        sub-folder is gathered up and turned into that sub-folder's own tree
+        first -- like a table of contents with a mini table of contents for
+        each chapter.
+
+        Returns:
+            The hash of this folder's tree.
+
+        """
+        entries: list[TreeEntry] = []
+        sub_folders: dict[str, dict[str, str]] = {}
+        for path, blob_hash in files.items():
+            first, slash, rest = path.partition("/")
+            if slash:
+                sub_folders.setdefault(first, {})[rest] = blob_hash
+            else:
+                entries.append(TreeEntry(name=first, entry_type="blob", hash=blob_hash))
+        for name, contents in sub_folders.items():
+            entries.append(TreeEntry(name=name, entry_type="tree", hash=self._write_tree(contents)))
+        _tree_hash, tree_content = build_tree(entries)
+        return self._store.write_object("tree", tree_content.encode())
+
+    def _read_tree(self, tree_hash: str, prefix: str = "") -> dict[str, str]:
+        """Flatten a tree (and its sub-trees) back into ``{path: blob hash}``."""
+        files: dict[str, str] = {}
+        for entry in parse_tree(self._store.read_object(tree_hash, "tree").decode()):
+            path = f"{prefix}{entry.name}"
+            if entry.entry_type == "tree":
+                files.update(self._read_tree(entry.hash, prefix=f"{path}/"))
+            else:
+                files[path] = entry.hash
+        return files
+
+    def _read_index(self) -> dict[str, str]:
+        """Read the staging area from disk."""
+        index_path = self._pygit_dir / INDEX_FILE
+        if not index_path.exists():
+            return {}
+        content = index_path.read_text(encoding="utf-8")
+        result: dict[str, str] = json.loads(content)
+        return result
+
+    def _write_index(self, index: dict[str, str]) -> None:
+        """Write the staging area to disk."""
+        index_path = self._pygit_dir / INDEX_FILE
+        index_path.write_text(json.dumps(index), encoding="utf-8")
+
+    def _get_branch_tip(self) -> str | None:
+        """Return the commit hash at the tip of the current branch."""
+        branch = self.current_branch()
+        branch_path = self._pygit_dir / REFS_DIR / branch
+        if not branch_path.exists():
+            return None
+        tip = branch_path.read_text(encoding="utf-8").strip()
+        return tip or None
+
+    def _set_branch_tip(self, commit_hash: str) -> None:
+        """Update the current branch to point to a commit."""
+        branch = self.current_branch()
+        branch_path = self._pygit_dir / REFS_DIR / branch
+        branch_path.write_text(commit_hash, encoding="utf-8")

pygit/tree.py

@@ -0,0 +1,62 @@
+"""Trees -- snapshots of directory structure.
+
+A tree is like a table of contents: it lists which files (blobs) and
+subdirectories (other trees) exist, along with their names and hashes.
+When you commit, Git builds a tree of the entire project.
+"""
+
+import json
+from dataclasses import dataclass
+
+from pygit.hashing import hash_object
+
+
+@dataclass(frozen=True, slots=True)
+class TreeEntry:
+    """One entry in a tree (a file or subdirectory).
+
+    Args:
+        name: The filename or directory name.
+        entry_type: "blob" for files, "tree" for directories.
+        hash: The SHA-1 hash of the blob or sub-tree.
+
+    """
+
+    name: str
+    entry_type: str
+    hash: str
+
+
+def build_tree(entries: list[TreeEntry]) -> tuple[str, str]:
+    """Build a tree object from a list of entries.
+
+    Sorts entries by name for consistency (same entries always produce
+    the same tree hash, regardless of insertion order).
+
+    Args:
+        entries: The tree entries (files and directories).
+
+    Returns:
+        A tuple of (tree_hash, serialized_tree_content).
+
+    """
+    sorted_entries = sorted(entries, key=lambda e: e.name)
+    content = json.dumps(
+        [{"name": e.name, "type": e.entry_type, "hash": e.hash} for e in sorted_entries]
+    )
+    tree_hash = hash_object("tree", content.encode())
+    return tree_hash, content
+
+
+def parse_tree(content: str) -> list[TreeEntry]:
+    """Deserialize a tree from its stored content.
+
+    Args:
+        content: The JSON-serialized tree content.
+
+    Returns:
+        A list of TreeEntry objects.
+
+    """
+    raw: list[dict[str, str]] = json.loads(content)
+    return [TreeEntry(name=e["name"], entry_type=e["type"], hash=e["hash"]) for e in raw]