ngit docs

How it works ​

ngit doesn't replace git. It replaces the forge, the layer GitHub or GitLab adds on top of git: the canonical copy, the pull requests, the issues, the releases, the CI, the accounts.

Two layers, pulled apart ​

A git repository is really two things:

  • State, the refs. Which commit main points at. Which commits are tagged v2.0. A small, constantly-changing set of names and hashes.
  • Data, the objects. The commits, trees and blobs themselves. Large, immutable, content-addressed.

On a forge, both live in the same place, and that place is authoritative. ngit separates them:

Lives onRole
State (refs)nostr relays, as signed eventsThe source of truth
Data (objects)ordinary git serversInterchangeable storage

When you git fetch, git-remote-nostr reads the current ref state from the relays, then fetches the matching objects from whichever git servers the repository announcement lists.

Because the refs are signed by the maintainer and replicated across relays, the git server is no longer authoritative, it's a cache. A repository can list several at once, hosted and self-hosted alike. A maintainer can add, drop, or swap providers without contributors re-cloning or changing the nostr:// URL.

What nostr provides ​

Nostr is a protocol where users publish signed events to relays, simple servers anyone can run. There's no central authority: identity is a keypair, and data is replicated across as many relays as you like.

ngit uses it for the things a forge would otherwise own:

  • Identity: you are a keypair, not an account on someone's server.
  • Discovery: repository announcements say where a repo's data and relays live.
  • State: the signed refs described above.
  • Collaboration: pull requests, issues, comments, labels, releases and CI results are all events.

GRASP servers ​

GRASP defines a repository-aware service that combines a Nostr relay and a Git server. When ngit init publishes an announcement naming a compatible GRASP server, that server creates the Git repository without a separate forge account or pre-created repository.

The repository announcement carries the service locations; signed Nostr state remains authoritative. A repository may use hosted or self-hosted GRASP services, or separate relay and Git infrastructure. The Repositories guide owns that hosting decision and the commands for changing it.

GRASP-08 extends the same model with authenticated, read-restricted private services. Private repositories require ngit v3+ and ngit-grasp v3+; see Private repositories for the current self-hosted path and its trust boundary.

nostr:// URLs ​

nostr://<npub>/<identifier>
nostr://<npub>/<relay-hint>/<identifier>

The relay hint is a bare domain, like relay.ngit.dev. It's optional but worth including: without it, ngit has to discover which relays carry the announcement, which is slower.

bash
# with a relay hint, preferred
git clone nostr://npub1abc.../relay.ngit.dev/my-project

# without, works but discovery is slower
git clone nostr://npub1abc.../my-project

# NIP-05 address, if someone gave you one
git clone nostr://danconwaydev.com/ngit

TIP

Don't guess NIP-05 addresses. user@domain forms only work if someone published one. Use the npub1... form unless you were given an address.

Once installed, these URLs work with plain git commands. git-remote-nostr is a remote helper: git discovers it by filename whenever it meets a nostr:// URL, which is why both binaries have to be on your PATH.

Where other clients fit ​

ngit is one client in a wider protocol ecosystem. Other command-line, desktop, web, community, and AI-assisted clients can read and publish the same kinds of events without making any one interface authoritative.

gitworkshop.dev is one browser client for the same data, not a server that owns it. Nothing in ngit depends on it being up. Browse repositories there at gitworkshop.dev/repos, or explore the GitNostr ecosystem for other interfaces and services.

Next ​