Repositories

Publishing

Run ngit init inside an existing git repository:

ngit init --name "My Project" --description "What it does" --defaults

This publishes a repository announcement and adds a nostr:// remote. With no --grasp-server, it uses your preferred GRASP server if you have one configured and falls back to the built-in defaults otherwise.

Choosing where it lives

A GRASP server is a relay and a git server in one, and creates the repository for you:

ngit init --name "My Project" --grasp-server grasp.example.com --defaults

Additional infrastructure supplements that preferred or default GRASP server:

ngit init \
  --name "My Project" \
  --additional-relay wss://relay.example.com \
  --additional-clone https://git.example.com/my-project.git \
  --defaults

The effective sets are additive:

relays = grasp-derived relays + additional relays
clones = grasp-derived clones + additional clones

To host without any GRASP server, opt out explicitly with an empty value and provide both halves of the hosting setup yourself:

ngit init \
  --name "My Project" \
  --grasp-server "" \
  --additional-relay wss://relay.example.com \
  --additional-clone https://git.example.com/my-project.git \
  --defaults

Supplying only --additional-relay or --additional-clone does not disable GRASP. A no-GRASP repository needs at least one relay and one Git clone URL. ngit checks both before signing the announcement.

--identifier is permanent

It becomes the NIP-34 d tag. Changing it doesn't rename the repository. It creates a different one at a different coordinate.

See the generated ngit init reference for the complete 3.0.0-rc.7 option set.

Cloning

git clone nostr://<npub>/<relay-hint>/<identifier>   # preferred
git clone nostr://<npub>/<identifier>                # slower discovery
git clone nostr://user@domain.example/<identifier>   # NIP-05, if given to you

The relay hint is a bare domain (relay.ngit.dev). Including it skips the discovery step.

Inspecting

ngit repo                    # what this repository is
ngit repo --offline          # from cache, no network

Shows the name, description, nostr:// URL, maintainers, relays, git servers, GRASP servers and hashtags. Run git fetch origin first if the cache may be stale.

Editing metadata

ngit repo edit preserves anything you don't mention:

ngit repo edit --description "New description"

Collections use targeted add/remove actions rather than replacing the whole list:

Setting	Add	Remove
GRASP server	--add-grasp-server URL	--remove-grasp-server URL
Additional relay	--add-additional-relay URL	--remove-additional-relay URL
Additional clone	--add-additional-clone URL	--remove-additional-clone URL
Hashtag	--add-hashtag TAG	--remove-hashtag TAG

They repeat and combine:

ngit repo edit \
  --remove-additional-relay wss://old.example.com \
  --add-additional-relay wss://new.example.com \
  --add-hashtag rust

To empty a collection, remove each value currently reported by ngit repo.

A few rules the CLI enforces:

• A GRASP-derived entry can't be removed as an additional entry. Remove the GRASP server instead; its paired relay and clone URL go together.
• An edit that would leave the repository with no relay, or no git server, fails before publishing anything. A metadata-only edit of an older malformed announcement also stops until the same edit repairs its hosting.

See the generated ngit repo edit reference for every action.

Swapping git servers

This is the payoff of keeping refs on nostr. Add the new server, remove the old one, and contributors do nothing:

ngit repo edit \
  --add-additional-clone https://new-host.example.com/my-project.git \
  --remove-additional-clone https://old-host.example.com/my-project.git

Every successful edit republishes the announcement. When the repository already has nostr state, ngit republishes that too, so newly added relays and servers get the authoritative refs immediately. If that second step fails, ngit prints an ngit sync recovery command. Run it.

Keeping servers in sync

ngit sync                     # push nostr state out to the git servers
ngit sync --ref-name main     # just one ref

Use it after adding a server, or when a server has fallen behind. See Troubleshooting for diverged refs.

Next

• Maintainers: invitations, roles, and lead changes
• Pull requests: contribute and review
• ngit repo reference: exact 3.0.0-rc.7 syntax