Troubleshooting

git-remote-nostr not found

fatal: Unable to find remote helper for 'nostr'

Git looks up remote helpers by filename on your PATH. Both binaries have to be there:

ngit --version
git-remote-nostr --version

If the second fails, your install only put ngit in place — see Install.

ngit repo says is_nostr_repo: false

Usually a cold cache, not a real answer. Check the remotes first, since that needs no cache at all:

git remote -v | grep nostr://

If a nostr:// remote is there, refresh and retry:

git fetch origin
ngit repo

ngit repo always exits 0, so don't treat a zero exit code as confirmation.

My PR didn't appear

Almost always the branch name. A PR is created only when the branch starts with pr/:

git branch --show-current

my-feature and feature/foo are plain pushes. Rename and push again:

git branch -m pr/my-feature
git push -u origin pr/my-feature

No push option can substitute for the prefix.

My PR description came out mangled

If it contains literal \n characters, you used ngit send --description with plain double quotes — the shell doesn't interpret \n there. Use $'...' or a file:

ngit send HEAD~2 --subject "Title" --description "$(cat description.md)"

If it came out as a single paragraph from git push -o description=..., that's the opposite problem: push options need literal \n, because git cannot carry real newlines through them. Don't feed a file into -o description= — use ngit send. See Pull requests.

Fix an already-published one with:

ngit pr set-cover-note <ID> --body "$(cat description.md)"

Push to a GRASP server times out

GRASP servers can go silent while indexing a large push. Raise the per-socket timeout:

git config nostr.http-io-timeout-ms 600000     # 10 minutes

Too many pr/* branches

By default every open and draft PR is advertised as a branch. On a busy repository:

git config nostr.auto-pr-branches false
git fetch --prune

ngit pr checkout <ID> still creates the branch you actually want, and it keeps working with git fetch and git pull.

Refs out of sync

When a git server has fallen behind the nostr state:

ngit sync
ngit sync --ref-name main

If a server is fast-forward ahead of nostr state and you trust it:

ngit sync --trust-server
git config --global nostr.trust-server-domains 'github.com;codeberg.org'

That only covers clean fast-forwards. Diverged refs always stop and ask — ngit prints a recovery command rather than choosing a side for you.

Ambiguous repository

With several nostr:// remotes, ngit fails rather than guessing. Name the one you mean:

ngit --repo upstream pr list

Before signing, ngit prints a target repository: <naddr> (source: ...) line on stderr — worth reading when something goes to the wrong place.

Ambiguous ID prefix

Short hex prefixes must be unique. If one isn't, ngit lists the matches — use a longer prefix or the full nevent1….

Cache directory not writable

NGIT_CACHE_DIR=/writable/path ngit repo

If the global cache is unavailable, ngit falls back to an in-memory cache. The repository cache has no such fallback: the git common directory must be writable.

Self-signed or internal CA

Build with the system certificate store:

cargo install ngit --features native-tls-roots

Still stuck

• ngit <command> --help for the exact flags on your version
• ngit --customize for every git config key
• -v / --verbose for what it's actually doing
• Report it at gitworkshop.dev/danconwaydev.com/ngit