Configuration

Almost everything is a git config key. Run ngit --customize for the built-in version of this page.

Precedence

Highest wins:

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

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

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

Relay defaults

Key	Environment	Used for
nostr.grasp-default-set	NGIT_GRASP_DEFAULT_SET	ngit init only
nostr.relay-default-set	NGIT_RELAY_DEFAULT_SET	Profile discovery, account bootstrapping
nostr.relay-announcement-indexer-set	NGIT_RELAY_ANNOUNCEMENT_INDEXER_SET	Repository announcement discovery
nostr.relay-blaster-set	NGIT_RELAY_BLASTER_SET	Announcement events only
nostr.relay-signer-fallback-set	NGIT_RELAY_SIGNER_FALLBACK_SET	Remote signer fallback

Built-in defaults

Default relays	wss://relay.damus.io, wss://relay.ditto.pub
Announcement indexer	wss://index.ngit.dev
Signer fallback	wss://bucket.coracle.social, wss://nos.lol, wss://relay.ditto.pub
Default GRASP servers	relay.ngit.dev, gitnostr.com

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. Useful when you'd rather not broadcast work to your own relays. Also available per-command as --repo-relay-only.

nostr.auto-pr-branches

git config nostr.auto-pr-branches false

Defaults to true, which advertises every open and draft PR as a pr/* branch. Set it to false on a busy repository and PR branches appear only once ngit pr checkout creates them — those branches keep working with git fetch and git pull as normal.

Run git fetch --prune once afterwards to clear branches fetched before you turned it off. To override a global false while cloning:

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

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

Key	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 npub or alias
nostr.signer-alias.<alias>	Alias-to-npub mapping
nostr.nsec	Credential-store entry name, or a plaintext nsec / ncryptsec
nostr.npub	Used for ncryptsec and remote signers
nostr.bunker-uri	Remote signer connection
nostr.bunker-app-key	Credential-store entry name for the remote signer
nostr.secret-storage	auto | file | 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. Plaintext nsec1… values are still accepted.

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