Design decisions

One file per decision. Each states the decision, the reasoning, the alternatives rejected, and the consequences — including the bad ones.

Transport

• 0001 — Git lives at the root namespace, REST lives under /api
• 0002 — The transport layer takes streams, not Request/Response
• 0013 — The request body is captured before anything else can await
• 0014 — A flush-only POST is a probe, not a malformed push
• 0003 — git/ is not a REST resource

Storage and durability

• 0004 — Object storage is the source of truth, local disk is a cache
• 0005 — One commit point per push, and it is a compare-and-swap
• 0006 — Entries carry no sequence number
• 0007 — Optimistic concurrency, never locks
• 0008 — The log is a binary format
• 0009 — The index holds a ref snapshot, not a diff
• 0010 — Orphaned entries are garbage, never corruption
• 0012 — Materialization is forward-only replay
• 0015 — Nothing holds a packfile in memory

Review

• 0016 — A pull request spans two logs, and lends objects rather than copying them

Open

• 0011 — Deferred decisions