ngit docs

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:

bash
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:

bash
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. It pushes your current default branch, publishes its signed state, and configures the upstream. No signup, pre-created empty repo, or second initial push is needed.

After that, commit and git push as normal.

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

bash
ngit repo

3. Clone someone else's ​

bash
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.

bash
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:

bash
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 ​

bash
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 on a tracking branch

The checked-out branch is linked to its upstream. While you are on it, git pull receives later PR updates.

Maintainers merge, then push to publish it:

bash
git switch main
ngit pr merge <ID>
git push origin main

ngit pr merge acts on the current branch and deliberately does not push. You get to look at the merge before publishing it.

IDs come from ngit pr list. A unique hex prefix works anywhere a full ID does, with or without the #: ngit pr view '#deadbeef'. Quote the # form so your shell doesn't treat it as a comment.

Next ​

Git collaboration, without the platform.

MIT licensed · guides reviewed against ngit 3.0.0-rc.7