# jelmer/dulwich architecture

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

- Interactive diagram: https://gitdiagram.com/jelmer/dulwich
- Repository: https://github.com/jelmer/dulwich

## Overview

Dulwich is a pure-Python Git library with a porcelain command layer and a lower-level repository API. A typical local workflow enters through the CLI or porcelain, reads or changes a repository’s working tree, index, objects, and refs, then reports results. Remote workflows use the client protocol to exchange refs and pack data, while server handlers expose repositories to peers. The README documents these API layers and Git compatibility; several subsystem links below reflect module roles and documented capabilities rather than inspected call sites.

Main entry points: [`dulwich/porcelain/__init__.py`](https://github.com/jelmer/dulwich/blob/main/dulwich/porcelain/__init__.py) (Porcelain API), [`dulwich/repo.py`](https://github.com/jelmer/dulwich/blob/main/dulwich/repo.py) (Repository API), [`dulwich/object_store.py`](https://github.com/jelmer/dulwich/blob/main/dulwich/object_store.py) (Object store), [`dulwich/server.py`](https://github.com/jelmer/dulwich/blob/main/dulwich/server.py) (Git server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_porcelain["Porcelain API<br/>[__init__.py]"]
end

subgraph group_local["Local Repository"]
  node_repo["Repository API<br/>[repo.py]"]
  node_index["Index<br/>[index.py]"]
  node_worktree["Working tree<br/>[worktree.py]"]
  node_refs["Refs and reflogs<br/>[refs.py]"]
end

subgraph group_history["Git Data Operations"]
  node_objects["Git objects<br/>[objects.py]"]
  node_objectstore["Object store<br/>[object_store.py]"]
  node_pack["Pack files<br/>[pack.py]"]
  node_diff["Diff and merge<br/>[diff.py]"]
  node_walk["History traversal<br/>[walk.py]"]
  node_archive["Archive output<br/>[archive.py]"]
end

subgraph group_network["Remote Protocols"]
  node_client["Git client<br/>[client.py]"]
  node_protocol["Wire protocol<br/>[protocol.py]"]
  node_server["Git server<br/>[server.py]"]
  node_httpserver["HTTP server<br/>[server.py]"]
end

subgraph group_extensions["Storage Integrations"]
  node_gcs["GCS object store<br/>[gcs.py]"]
  node_swift["Swift backend<br/>[swift.py]"]
end

node_user(("Git library user"))
node_peer(("Git peer"))
node_cloud[("Cloud storage")]

node_user -->|"runs commands"| node_cli
node_user -->|"calls API"| node_porcelain
node_cli -->|"dispatches commands"| node_porcelain
node_porcelain -->|"uses repository"| node_repo
node_repo -->|"accesses objects"| node_objectstore
node_repo -->|"manages refs"| node_refs
node_porcelain -->|"updates staging"| node_index
node_porcelain -->|"changes files"| node_worktree
node_index -->|"stages objects"| node_objectstore
node_objectstore -->|"stores objects"| node_objects
node_objectstore -->|"reads and writes packs"| node_pack
node_porcelain -->|"computes changes"| node_diff
node_porcelain -->|"traverses history"| node_walk
node_porcelain -->|"exports repository"| node_archive
node_client -->|"exchanges Git data"| node_protocol
node_client -->|"updates local repository"| node_repo
node_client -->|"fetches or pushes"| node_peer
node_peer -->|"requests repository service"| node_server
node_server -->|"handles wire messages"| node_protocol
node_server -->|"serves repository"| node_repo
node_httpserver -->|"dispatches services"| node_server
node_gcs -.->|"reads and writes blobs"| node_cloud
node_swift -.->|"stores repository data"| node_cloud

click node_cli "https://github.com/jelmer/dulwich/blob/main/dulwich/cli.py"
click node_porcelain "https://github.com/jelmer/dulwich/blob/main/dulwich/porcelain/__init__.py"
click node_repo "https://github.com/jelmer/dulwich/blob/main/dulwich/repo.py"
click node_index "https://github.com/jelmer/dulwich/blob/main/dulwich/index.py"
click node_worktree "https://github.com/jelmer/dulwich/blob/main/dulwich/worktree.py"
click node_refs "https://github.com/jelmer/dulwich/blob/main/dulwich/refs.py"
click node_objects "https://github.com/jelmer/dulwich/blob/main/dulwich/objects.py"
click node_objectstore "https://github.com/jelmer/dulwich/blob/main/dulwich/object_store.py"
click node_pack "https://github.com/jelmer/dulwich/blob/main/dulwich/pack.py"
click node_diff "https://github.com/jelmer/dulwich/blob/main/dulwich/diff.py"
click node_walk "https://github.com/jelmer/dulwich/blob/main/dulwich/walk.py"
click node_archive "https://github.com/jelmer/dulwich/blob/main/dulwich/archive.py"
click node_client "https://github.com/jelmer/dulwich/blob/main/dulwich/client.py"
click node_protocol "https://github.com/jelmer/dulwich/blob/main/dulwich/protocol.py"
click node_server "https://github.com/jelmer/dulwich/blob/main/dulwich/server.py"
click node_httpserver "https://github.com/jelmer/dulwich/blob/main/dulwich/aiohttp/server.py"
click node_gcs "https://github.com/jelmer/dulwich/blob/main/dulwich/cloud/gcs.py"
click node_swift "https://github.com/jelmer/dulwich/blob/main/contrib/swift.py"

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_cli,node_porcelain,node_user toneBlue
class node_repo,node_index,node_worktree,node_refs,node_cloud toneAmber
class node_objects,node_objectstore,node_pack,node_diff,node_walk,node_archive toneMint
class node_client,node_protocol,node_server,node_httpserver toneRose
class node_gcs,node_swift,node_peer toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/jelmer/dulwich/blob/main/dulwich/cli.py): `dulwich/cli.py`
- [Porcelain API](https://github.com/jelmer/dulwich/blob/main/dulwich/porcelain/__init__.py): `dulwich/porcelain/__init__.py`

### Local Repository

- [Repository API](https://github.com/jelmer/dulwich/blob/main/dulwich/repo.py): `dulwich/repo.py`
- [Index](https://github.com/jelmer/dulwich/blob/main/dulwich/index.py): `dulwich/index.py`
- [Working tree](https://github.com/jelmer/dulwich/blob/main/dulwich/worktree.py): `dulwich/worktree.py`
- [Refs and reflogs](https://github.com/jelmer/dulwich/blob/main/dulwich/refs.py): `dulwich/refs.py`

### Git Data Operations

- [Git objects](https://github.com/jelmer/dulwich/blob/main/dulwich/objects.py): `dulwich/objects.py`
- [Object store](https://github.com/jelmer/dulwich/blob/main/dulwich/object_store.py): `dulwich/object_store.py`
- [Pack files](https://github.com/jelmer/dulwich/blob/main/dulwich/pack.py): `dulwich/pack.py`
- [Diff and merge](https://github.com/jelmer/dulwich/blob/main/dulwich/diff.py): `dulwich/diff.py`
- [History traversal](https://github.com/jelmer/dulwich/blob/main/dulwich/walk.py): `dulwich/walk.py`
- [Archive output](https://github.com/jelmer/dulwich/blob/main/dulwich/archive.py): `dulwich/archive.py`

### Remote Protocols

- [Git client](https://github.com/jelmer/dulwich/blob/main/dulwich/client.py): `dulwich/client.py`
- [Wire protocol](https://github.com/jelmer/dulwich/blob/main/dulwich/protocol.py): `dulwich/protocol.py`
- [Git server](https://github.com/jelmer/dulwich/blob/main/dulwich/server.py): `dulwich/server.py`
- [HTTP server](https://github.com/jelmer/dulwich/blob/main/dulwich/aiohttp/server.py): `dulwich/aiohttp/server.py`

### Storage Integrations

- [GCS object store](https://github.com/jelmer/dulwich/blob/main/dulwich/cloud/gcs.py): `dulwich/cloud/gcs.py`
- [Swift backend](https://github.com/jelmer/dulwich/blob/main/contrib/swift.py): `contrib/swift.py`

### Other components

- **Git library user**
- **Git peer**
- **Cloud storage**

## Connections

- Git library user → CLI: runs commands
- Git library user → Porcelain API: calls API
- CLI → Porcelain API: dispatches commands
- Porcelain API → Repository API: uses repository
- Repository API → Object store: accesses objects
- Repository API → Refs and reflogs: manages refs
- Porcelain API → Index: updates staging
- Porcelain API → Working tree: changes files
- Index → Object store: stages objects
- Object store → Git objects: stores objects
- Object store → Pack files: reads and writes packs
- Porcelain API → Diff and merge: computes changes
- Porcelain API → History traversal: traverses history
- Porcelain API → Archive output: exports repository
- Git client → Wire protocol: exchanges Git data
- Git client → Repository API: updates local repository
- Git client → Git peer: fetches or pushes
- Git peer → Git server: requests repository service
- Git server → Wire protocol: handles wire messages
- Git server → Repository API: serves repository
- HTTP server → Git server: dispatches services
- GCS object store → Cloud storage: reads and writes blobs
- Swift backend → Cloud storage: stores repository data