ngit docs

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:

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

bash
git remote -v | grep nostr://

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

bash
git fetch origin
ngit repo

ngit repo always exits 0, so don't treat a zero exit code as confirmation. In automation, request --json and inspect the reported state.

My PR didn't appear ​

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

bash
git branch --show-current

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

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

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

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

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

PR branches are missing, or old ones remain ​

ngit does not download every open and draft PR branch by default. Check out the one you want:

bash
ngit pr checkout <ID>

That local branch tracks its upstream, so later git fetch, git pull, and git push work normally. To fetch every open and draft PR branch instead:

bash
git config nostr.auto-pr-branches true

Branches fetched by an older ngit do not disappear automatically. Remove their stale tracking refs once with git fetch --prune.

Refs out of sync ​

When a git server has fallen behind the nostr state:

bash
ngit sync
ngit sync --ref-name main

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

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

bash
ngit --repo upstream pr list

Before signing, ngit prints a target repository: <naddr> (source: ...) line on stderr. It's 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 ​

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

bash
cargo install ngit --features native-tls-roots

Still stuck ​

Git collaboration, without the platform.

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