# geoffgarside/git.framework architecture

> Architecture diagram of the GitHub repository geoffgarside/git.framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geoffgarside/git.framework
- Repository: https://github.com/geoffgarside/git.framework

## Overview

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.

Main entry points: [`Source/GITRepo.h`](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRepo.h) (Repo), [`Source/GITCommit.h`](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITCommit.h) (Commit), [`Source/GITPackCollection.h`](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackCollection.h) (Pack collection), [`Source/GITGraph.h`](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITGraph.h) (History graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core framework"]
  node_git_api["Git API<br/>public umbrella<br/>[Git.h]"]
  node_repo["Repo<br/>façade<br/>[GITRepo.h]"]
  node_object_model["Git object<br/>domain model<br/>[GITObject.h]"]
  node_commit["Commit<br/>domain model<br/>[GITCommit.h]"]
  node_tree["Tree<br/>domain model<br/>[GITTree.h]"]
  node_blob["Blob<br/>domain model<br/>[GITBlob.h]"]
  node_tag["Tag<br/>domain model<br/>[GITTag.h]"]
  node_graph{{"History graph<br/>rev graph<br/>[GITGraph.h]"}}
  node_rev_list{{"Rev list<br/>revision traversal<br/>[GITRevList.h]"}}
  node_commit_enum{{"Commit enum<br/>commit walker"}}
end

subgraph group_storage["Storage layer"]
  node_ref(("Ref<br/>[GITRef.h]"))
  node_branch(("Branch<br/>ref view<br/>[GITBranch.h]"))
  node_packed_refs(("Packed refs<br/>ref enumerator"))
  node_loose_object[("Loose object<br/>object store<br/>[GITLooseObject.h]")]
  node_pack_collection[("Pack collection<br/>pack coordinator")]
  node_pack_file[("Pack file<br/>pack reader<br/>[GITPackFile.h]")]
  node_pack_index[("Pack index<br/>index reader<br/>[GITPackIndex.h]")]
end

subgraph group_support["Support code"]
  node_parsing["Parsing"]
  node_actor_parse["Actor parse<br/>parser<br/>[GITActor+Parsing.h]"]
  node_categories["Foundation cats<br/>utility extensions"]
end

subgraph group_delivery["Delivery"]
  node_bridge["BridgeSupport<br/>interop metadata<br/>[Git.bridgesupport]"]
  node_build_docs["Build & docs<br/>packaging<br/>[project.pbxproj]"]
  node_tests["Tests<br/>ruby suite"]
end

node_git_api -->|"exports"| node_repo
node_repo -->|"resolves"| node_ref
node_repo -->|"lists"| node_branch
node_repo -->|"reads"| node_loose_object
node_repo -->|"reads"| node_pack_collection
node_packed_refs -->|"yields"| node_ref
node_pack_collection -->|"coordinates"| node_pack_file
node_pack_collection -->|"coordinates"| node_pack_index
node_pack_index -->|"locates"| node_pack_file
node_loose_object -->|"materializes"| node_object_model
node_pack_file -->|"materializes"| node_object_model
node_parsing -->|"parses"| node_object_model
node_actor_parse -->|"supports"| node_commit
node_commit -->|"references"| node_tree
node_tree -->|"contains"| node_blob
node_commit -->|"reachable via"| node_tag
node_commit_enum -->|"walks"| node_graph
node_rev_list -->|"queries"| node_graph
node_graph -->|"navigates"| node_commit
node_categories -.->|"enables"| node_parsing
node_bridge -->|"bridges"| node_git_api
node_build_docs -.->|"generates"| node_bridge
node_tests -->|"exercises"| node_repo
node_tests -->|"verifies"| node_parsing

click node_git_api "https://github.com/geoffgarside/git.framework/blob/develop/Source/Git.h"
click node_repo "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRepo.h"
click node_ref "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRef.h"
click node_branch "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITBranch.h"
click node_packed_refs "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackedRefsEnumerator.h"
click node_loose_object "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITLooseObject.h"
click node_pack_collection "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackCollection.h"
click node_pack_file "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackFile.h"
click node_pack_index "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackIndex.h"
click node_object_model "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITObject.h"
click node_commit "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITCommit.h"
click node_tree "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITTree.h"
click node_blob "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITBlob.h"
click node_tag "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITTag.h"
click node_graph "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITGraph.h"
click node_rev_list "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRevList.h"
click node_commit_enum "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITCommitEnumerator.h"
click node_parsing "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITObject+Parsing.h"
click node_actor_parse "https://github.com/geoffgarside/git.framework/blob/develop/Source/GITActor+Parsing.h"
click node_categories "https://github.com/geoffgarside/git.framework/tree/develop/Source/Category"
click node_bridge "https://github.com/geoffgarside/git.framework/blob/develop/Resource/BridgeSupport/Git.bridgesupport"
click node_build_docs "https://github.com/geoffgarside/git.framework/blob/develop/Git.xcodeproj/project.pbxproj"
click node_tests "https://github.com/geoffgarside/git.framework/tree/develop/Test/Unit"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_git_api,node_repo,node_object_model,node_commit,node_tree,node_blob,node_tag,node_graph,node_rev_list,node_commit_enum toneBlue
class node_ref,node_branch,node_packed_refs,node_loose_object,node_pack_collection,node_pack_file,node_pack_index toneAmber
class node_parsing,node_actor_parse,node_categories toneMint
class node_bridge,node_build_docs,node_tests toneRose
```

## Components

### Core framework

Public Git domain API and repository orchestration.

- [Git API](https://github.com/geoffgarside/git.framework/blob/develop/Source/Git.h): public umbrella · Top-level framework header that exposes the Objective-C surface. · `Source/Git.h`
- [Repo](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRepo.h): façade · Main entry point for opening repositories and coordinating lookup and traversal. · `Source/GITRepo.h`
- [Git object](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITObject.h): domain model · Base object abstraction for commits, trees, blobs, and tags. · `Source/GITObject.h`
- [Commit](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITCommit.h): domain model · Commit object wrapper with parent and message semantics. · `Source/GITCommit.h`
- [Tree](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITTree.h): domain model · Tree object wrapper for directory structure in the repository. · `Source/GITTree.h`
- [Blob](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITBlob.h): domain model · Blob object wrapper for file contents. · `Source/GITBlob.h`
- [Tag](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITTag.h): domain model · Annotated tag object wrapper. · `Source/GITTag.h`
- [History graph](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITGraph.h): rev graph · Builds commit graphs for traversal and revision listing. · `Source/GITGraph.h`
- [Rev list](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRevList.h): revision traversal · Implements revision enumeration and history selection over commits. · `Source/GITRevList.h`
- [Commit enum](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITCommitEnumerator.h): commit walker · Walks commit history in a chosen order. · `Source/GITCommitEnumerator.h`

### Storage layer

On-disk object, ref, and packfile adapters.

- [Ref](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITRef.h): symbol ref · Represents branch and reference names that point to object hashes. · `Source/GITRef.h`
- [Branch](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITBranch.h): ref view · Branch-specific ref abstraction layered on top of repository references. · `Source/GITBranch.h`
- [Packed refs](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackedRefsEnumerator.h): ref enumerator · Enumerates refs stored in packed-refs form. · `Source/GITPackedRefsEnumerator.h`
- [Loose object](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITLooseObject.h): object store · Reads individual Git objects from loose files in .git/objects. · `Source/GITLooseObject.h`
- [Pack collection](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackCollection.h): pack coordinator · Finds and coordinates packed objects across pack files and indexes. · `Source/GITPackCollection.h`
- [Pack file](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackFile.h): pack reader · Reads .pack data and resolves packed objects. · `Source/GITPackFile.h`
- [Pack index](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITPackIndex.h): index reader · Reads .idx files to locate packed objects inside pack files. · `Source/GITPackIndex.h`

### Support code

Parsing helpers and low-level Foundation categories.

- [Parsing](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITObject+Parsing.h): binary parsing · Transforms raw Git bytes into typed model objects. · `Source/GITObject+Parsing.h`
- [Actor parse](https://github.com/geoffgarside/git.framework/blob/develop/Source/GITActor+Parsing.h): parser · Parses author and committer identity records. · `Source/GITActor+Parsing.h`
- [Foundation cats](https://github.com/geoffgarside/git.framework/tree/develop/Source/Category): utility extensions · NSData, NSRange, and NSTimeZone helpers for Git-specific binary and time handling. · `Source/Category`

### Delivery

Build, packaging, docs, bridging, and tests.

- [BridgeSupport](https://github.com/geoffgarside/git.framework/blob/develop/Resource/BridgeSupport/Git.bridgesupport): interop metadata · Exposes framework symbols to bridged runtimes such as Ruby-based Cocoa environments. · `Resource/BridgeSupport/Git.bridgesupport`
- [Build & docs](https://github.com/geoffgarside/git.framework/blob/develop/Git.xcodeproj/project.pbxproj): packaging · Xcode project, Rake automation, version metadata, and documentation assets. · `Git.xcodeproj/project.pbxproj`
- [Tests](https://github.com/geoffgarside/git.framework/tree/develop/Test/Unit): ruby suite · MacRuby/Ruby-based validation suite for repository behavior and parsing. · `Test/Unit`

## Connections

- Git API → Repo: exports · The umbrella header exposes the main repository API.
- Repo → Ref: resolves · Repository lookup starts by resolving names to refs.
- Repo → Branch: lists · Branches are derived from repository refs.
- Repo → Loose object: reads · Repository access may load loose objects directly.
- Repo → Pack collection: reads · Repository access also resolves objects through packs.
- Packed refs → Ref: yields · Packed refs are turned into reference objects.
- Pack collection → Pack file: coordinates · The collection manages pack files as a set.
- Pack collection → Pack index: coordinates · The collection pairs packs with their indexes.
- Pack index → Pack file: locates · Indexes provide offsets into pack files.
- Loose object → Git object: materializes · Loose object bytes become Git domain objects.
- Pack file → Git object: materializes · Packed object bytes become Git domain objects.
- Parsing → Git object: parses · Raw object data is converted into typed objects.
- Actor parse → Commit: supports · Commit parsing depends on parsed actor metadata.
- Commit → Tree: references · Commits point to tree snapshots.
- Tree → Blob: contains · Trees contain blob entries and subtrees.
- Commit → Tag: reachable via · Tags can reference commits and other objects.
- Commit enum → History graph: walks · Commit enumeration builds on the history graph.
- Rev list → History graph: queries · Revision listing uses graph structure for traversal.
- History graph → Commit: navigates · The history graph traverses commits and their parents.
- Foundation cats → Parsing: enables · Utility categories support checksum, compression, time, and range parsing.
- BridgeSupport → Git API: bridges · BridgeSupport exposes the framework API to other runtimes.
- Build & docs → BridgeSupport: generates · Build and packaging steps include bridge metadata and documentation assets.
- Tests → Repo: exercises · The test suite drives repository-level behavior.
- Tests → Parsing: verifies · Tests validate parsing and object conversion paths.