Configuration

Almost everything is a git config key. Run this on the installed version for ngit's source-owned configuration reference:

ngit --customize

This page explains the most useful settings and how precedence works. Exact command flags come from the generated 3.0.0-rc.7 reference.

Precedence

Highest wins:

1. Environment variable
2. Local git config for this repository
3. Global git config
4. Built-in default

git config nostr.relay-default-set 'wss://a.example.com;wss://b.example.com'
git config --global nostr.relay-default-set 'wss://a.example.com'
NGIT_RELAY_DEFAULT_SET='wss://a.example.com' ngit repo

Relay set values are semicolon-separated URLs with no spaces.

Relay defaults

Git config	Environment	Used for
nostr.grasp-default-set	NGIT_GRASP_DEFAULT_SET	Providers used by ngit init
nostr.relay-default-set	NGIT_RELAY_DEFAULT_SET	Profile discovery and account bootstrap
nostr.relay-announcement-indexer-set	NGIT_RELAY_ANNOUNCEMENT_INDEXER_SET	Repository discovery
nostr.relay-blaster-set	NGIT_RELAY_BLASTER_SET	Announcement publication
nostr.relay-signer-fallback-set	NGIT_RELAY_SIGNER_FALLBACK_SET	Remote-signer fallback

Behaviour

nostr.repo-relay-only

git config nostr.repo-relay-only true

Publish only to the repository's relays, skipping your personal and default relay sets. This is useful when you'd rather not broadcast work to your own relays. It is also available per-command as --repo-relay-only.

nostr.auto-pr-branches

git config nostr.auto-pr-branches true

Defaults to false. Routine clones and fetches do not download every open and draft PR branch. ngit pr checkout <ID> opts one PR in by creating a local branch linked to its upstream. That branch keeps working with git fetch, git pull, and git push.

Set the option to true to restore automatic PR branches. Add --global if you want that behaviour in every repository. Tracking refs fetched by an older ngit remain until you remove them once with:

git fetch --prune

An unset option uses the new false default in fresh and existing clones. To enable automatic PR branches during the initial clone:

git clone --config nostr.auto-pr-branches=true <NOSTR-URL>

Output modes

-q / --quiet suppresses progress, routine status, update notices, and skill reminders. Primary results, prompts, warnings, and failures stay visible. It conflicts with -v / --verbose.

For automation, prefer --json so stdout contains one machine-readable document. Add --quiet only when you also want to reduce non-essential stderr output.

nostr.trust-server-domains

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

Git server hostnames that ngit sync may trust when they are fast-forward ahead of nostr state, without needing --trust-server each time. This covers only clean fast-forwards. Diverged refs always stop for manual resolution.

nostr.nostate

git config nostr.nostate true

Don't publish a state event when pushing to a nostr remote.

nostr.skill-reminders

git config nostr.skill-reminders false     # or: ngit skill opt-out --local

Silence the coding-agent skill setup and update reminders.

Timeouts

Git config	Environment	Default
nostr.http-connect-timeout-ms	NGIT_HTTP_CONNECT_TIMEOUT_MS	3000
nostr.http-io-timeout-ms	NGIT_HTTP_IO_TIMEOUT_MS	15000

The I/O timeout is a per-socket send/receive timeout. Raise it for large pushes to GRASP servers, which can go quiet while indexing:

git config nostr.http-io-timeout-ms 600000

Login

These are normally written by ngit account login rather than set by hand:

Key	Holds
nostr.signer	Selected public key or alias
nostr.signer-alias.<alias>	Alias-to-public-key mapping
nostr.nsec	Credential-store entry name
nostr.npub	Public key used with encrypted or remote signers
nostr.bunker-uri	Remote-signer connection
nostr.bunker-app-key	Credential-store entry name for the signer connection
nostr.secret-storage	auto, file, or git-config

Secrets normally live in the OS credential store, or ngit's file store when there isn't one. In that case nostr.nsec holds the entry name under keyring service nostr, not the key. Do not set plaintext secret material in git config.

git config nostr.signer alice                      # default signer for this repo
git config nostr.signer-alias.alice npub1...       # portable alias mapping
git -c nostr.signer=alice push origin pr/topic     # one command only

Cache

NGIT_CACHE_DIR=/writable/path ngit repo

Overrides the platform directory for ngit's global event cache. If that directory isn't writable, ngit falls back to an in-memory cache.

Repository caches do not have that fallback. The git common directory must be writable.

Implementation details

nostr.nip05, nostr.protocol-push and nostr.repo are set by ngit for efficiency. You shouldn't need to touch them.

Next

• Accounts & keys
• Troubleshooting
• Guide index