From c80173e5b5a1817f87a28dac5e9b3f3cf138495e Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Thu, 5 Mar 2026 10:18:02 +0000 Subject: add architecture explainer to ngit skill Explain the two-layer model: git state (refs) on Nostr relays, git data (objects) on git servers, and how grasp servers combine both. Covers decentralisation and ease of switching providers. --- skills/ngit/SKILL.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'skills') diff --git a/skills/ngit/SKILL.md b/skills/ngit/SKILL.md index 5c4fc1c..9773bff 100644 --- a/skills/ngit/SKILL.md +++ b/skills/ngit/SKILL.md @@ -13,6 +13,17 @@ ngit makes `clone`, `fetch`, `push` work with `nostr://` URLs and adds a CLI for - Install: `curl -Ls https://ngit.dev/install.sh | bash` (installs `ngit` and `git-remote-nostr`) - Web UI: https://gitworkshop.dev +## How it works + +Git has two distinct layers that ngit separates: + +- **Git state (refs)** — which commit each branch/tag points to — is published as signed events on Nostr relays. This is the source of truth for the repository. +- **Git data (objects)** — the actual commits, trees, and blobs — is stored on ordinary git servers (any server that speaks the git protocol). + +When you `git fetch`, `git-remote-nostr` reads the current ref state from Nostr relays, then fetches the corresponding objects from the git server(s) listed in the repository announcement. Because the state lives on Nostr and the data can live anywhere, git servers are interchangeable — switching providers requires no coordination with contributors. + +**Grasp servers** are a convenience: they combine a Nostr relay and a git server into a single hosted service (e.g. `relay.ngit.dev`), so a single URL covers both layers. You can use separate relays and git servers if you prefer. + ## Key rules - **Always use `--json`** on `ngit` commands when reading output — far easier to parse than human-readable text. `git` commands do not support `--json`. -- cgit v1.2.3