geoffgarside/git.framework

1. This repo is a Cocoa/Foundation framework, not an app: Git.framework provides an Objective-C API for reading and partially writing Git repositories on macOS (and potentially iPhone OS). The core boundary is the local .git directory on disk; most subsystems translate repository files and binary formats into Objective-C objects.

2. The top-level API surface lives in Source/Git.h and the GIT* classes. These model Git concepts directly: repository, refs, branches, commits, tags, trees, blobs, objects, pack files, pack indexes, graphs, and revision enumeration. The architecture is object-centric, with each Git storage format wrapped by a corresponding Cocoa class.

3. GITRepo is the main orchestration entry point. It ties together object lookup, ref resolution, and commit/history traversal. From an architecture perspective, it is the façade that other code would use to open a repository and ask for branches, objects, or revision lists.

4. Object storage is split into two paths: loose objects and packed objects. GITLooseObject handles individual object files, while GITPackCollection, GITPackFile, GITPackIndex, GITPackObject, and the related placeholder/versioned classes handle .pack and .idx data. This is a major boundary in the design because Git reads must transparently resolve an object from either storage mechanism.

5. Binary parsing is a dedicated layer. Source/GITObject+Parsing, GITCommit+Parsing, GITActor+Parsing, and GITTreeItem-related code translate raw Git data into strongly typed model objects. The data flow is: disk bytes → parsed Git object → domain object (commit/tree/blob/tag).

6. Ref handling is isolated from object storage. GITRef, GITBranch, GITRefResolver, and GITPackedRefsEnumerator cover .git/refs and packed refs, allowing the framework to map symbolic names to object hashes and then to actual objects. This boundary matters because refs are the indirection layer between branch names and commit objects.

7. History traversal is represented by GITCommitEnumerator, GITRevList, GITGraph, and GITGraphNode. These classes build and walk commit graphs in breadth-first or depth-first order and support a subset of git rev-list. The history subsystem sits on top of object parsing and ref resolution, not beside them.

8. Data types used throughout the framework have small utility extensions under Source/Category. There are NSData categories for CRC32, compression, delta patching, SHA1, and searching; NSRange and NSTimeZone categories support parsing and time handling. These are low-level helpers that enable Git’s binary formats and timestamp semantics without adding separate subsystems.

9. The pack-writing side exists but is clearly less mature than reading. GITPackFileWriter, GITPackIndexWriter, and the versioned placeholder classes indicate support for generating pack/index files, but the README notes deltas are unsupported and the API still needs work. So the architecture includes a write pipeline, but read paths are the primary production feature.

10. The repository includes BridgeSupport metadata in Resource/BridgeSupport/Git.bridgesupport, which exposes C-level symbols to bridged runtimes such as MacRuby or PyObjC. This is an interoperability boundary: the framework is intended to be used not only from Objective-C, but also from other Cocoa-compatible languages.

11. Build, packaging, and docs are part of the repo’s delivery architecture. The Xcode project builds the framework; Rakefile automates builds, tab checks, and BridgeSupport generation; Documentation/doxyclean and the Graffle doc assets support generated API docs. Resource/Info.plist and version files define framework metadata and versioning.

12. Tests are organized as a Ruby/MacRuby-based suite under Test/Unit, with helpers in Test/Support. That tells you the validation layer is external to the Objective-C runtime itself and likely exercises the framework from a bridged scripting environment, which is useful for verifying parsing and repository behavior against real Git data.

13. In diagram form, the main flow is: repository filesystem data → refs and pack/loose object readers → parsers/model objects → traversal/graph/rev-list services → client API through GITRepo and related classes. The key architectural distinction is between storage-format adapters at the bottom and Git-domain abstractions at the top.