Quickstart

Everything below assumes ngit and git-remote-nostr are on your PATH — see Install.

1. Get an identity

You are a keypair, not an account. Either bring one or make one:

ngit account login          # existing nostr key, or a NIP-46 remote signer
ngit account create --name "Alice"

Your secret goes into your OS credential store, not into git config. See Accounts & keys for remote signers, aliases and CI.

2. Publish a repository

From inside an existing git repository:

ngit init --name "My Project" --description "What it does" --defaults

That publishes a repository announcement to nostr and, because it defaults to a GRASP server, creates the git repository on the server for you — no signup or pre-created empty repo needed.

It also adds a nostr:// remote. Push as normal:

git push -u origin main

Check what you published, and get the URL to share:

ngit repo

3. Clone someone else's

git clone nostr://danconwaydev.com/relay.ngit.dev/ngit

Plain git. No ngit subcommand — git-remote-nostr handles the URL.

4. Open a pull request

The one rule

A branch becomes a pull request only if its name starts with pr/.

pr/my-feature opens a PR. my-feature and feature/foo are ordinary pushes and will never create one, no matter what push options you pass.

git checkout -b pr/my-feature
# ... commits ...
git push -u origin pr/my-feature

With a single commit, that's it — the commit subject becomes the PR title and the body becomes its description.

With several commits, give it a title explicitly:

git push -u origin pr/my-feature \
  -o 'title=Add retry logic' \
  -o 'description=Retries transient relay failures.\n\nCloses #deadbeef'

Note the literal \n characters. Git cannot pass real newlines through push options, so ngit's parser converts \n for you. Don't use $'...' quoting here, and don't try to feed a file into -o description= — use ngit send for anything longer.

Updating a PR is just another push to the same branch, --force included.

5. Review and merge

ngit pr list                    # what's open
ngit pr view <ID>               # read one
ngit pr view <ID> --comments    # with discussion
ngit pr comment <ID> --body "Looks good"
ngit pr checkout <ID>           # try it locally

Maintainers merge, then push to publish it:

ngit merge <ID>
git push origin main

ngit merge makes the merge commit but deliberately does not push — you get to look at it first.

IDs come from ngit pr list. A unique hex prefix works anywhere a full ID does, with or without the #: ngit pr view #deadbeef.

Next

• Pull requests — stacks, targeting, the full lifecycle
• Issues — create, label, auto-resolve from commits
• How it works — why refs live on relays
• Commands — everything on one page