ngit docs

Install ​

ngit ships two binaries, and both must be on your PATH:

  • ngit: the CLI
  • git-remote-nostr: a small launcher that git discovers by filename whenever it meets a nostr:// URL

git-remote-nostr contains almost nothing; the implementation lives in ngit. But without it on your PATH, git clone nostr://... fails with an unknown protocol error, so install them together.

One-line install ​

bash
curl -fsSL https://ngit.dev/install.sh | bash
powershell
iwr -useb https://ngit.dev/install.ps1 | iex
bash
cargo install ngit
bash
nix profile add 'git+https://ngit.dev/ngit.git?ref=stable'

The Shell and PowerShell installers install ngit 3.0.3. For a new installation, they download the matching binaries, verify their checksums, and install both. You can rerun them to update an older installation, even if it has no ngit update command.

If they detect a Cargo installation, they update it through Cargo in the same location, using the default registry and default features. Custom source and feature selections are not preserved. To switch to downloaded binaries, run the Shell installer with --method standalone or the PowerShell installer with -Method standalone. This leaves the Cargo copy in place; follow any PATH warning so your terminal uses the new copy.

The Cargo command installs the latest stable crate; the Nix command follows the stable branch, which always points at the latest stable release.

With cargo ​

bash
cargo install ngit

Requires rust and cargo. Make sure ~/.cargo/bin is on your PATH. Installing the ngit crate provides both binaries.

To install an exact version, including a release candidate:

bash
cargo install ngit --version <version>

Cargo only selects a pre-release when you name it exactly; plain cargo install ngit always resolves to the latest stable release.

With nix ​

Into your profile ​

bash
nix profile add 'git+https://ngit.dev/ngit.git?ref=stable'

One package, both binaries. ngit and git-remote-nostr land on your PATH together.

Then the usual profile management:

bash
nix profile list                              # find its index or name
nix profile remove ngit

The stable branch always points at the newest promoted stable release, so nix profile upgrade moves you forward without editing the URL. Release candidates never land on it.

Older Nix

nix profile add was called nix profile install before Nix 2.25. If add isn't recognised, use install. The arguments are identical.

If flakes aren't enabled, either add experimental-features = nix-command flakes to your nix.conf, or pass it per command:

bash
nix --extra-experimental-features "nix-command flakes" \
  profile add 'git+https://ngit.dev/ngit.git?ref=stable'

Without installing ​

To try it, or to get both binaries on your PATH for one shell session:

bash
nix shell 'git+https://ngit.dev/ngit.git?ref=stable'

Prefer this over nix run, which only exposes ngit. git-remote-nostr wouldn't be on your PATH, so git clone nostr://... would fail.

In a flake ​

Add it as an input:

nix
{
  inputs.ngit.url = "git+https://ngit.dev/ngit.git?ref=stable";
}

Then include the package:

nix
inputs.ngit.packages."${pkgs.system}".default

Your flake.lock pins the exact revision that stable resolved to, so builds stay reproducible. Run nix flake update ngit to move to a newer stable release.

Prebuilt binaries ​

Download the stable release archive for your platform and put both ngit and git-remote-nostr on your PATH:

Choose the build that matches the operating system and runtime:

BuildTarget and compatibility
macOS universalIntel and Apple Silicon; macOS 10.13 High Sierra or newer
Linux x86-64, glibcAny x86-64 distribution with glibc 2.17 or newer, including Ubuntu 14.04+, Debian 8+, RHEL/CentOS 7+, Fedora 21+, openSUSE, and Arch
Linux aarch64, glibcAny aarch64/arm64 distribution with glibc 2.17 or newer, including Ubuntu 20.04+, Debian 11+, Amazon Linux 2, AWS Graviton, and Raspberry Pi OS 64-bit
Linux x86-64, static muslAlpine 3.12+, Distroless and scratch containers, and systems where a dynamically linked glibc build is unsuitable
Windows x64Windows 7 SP1 or Server 2008 R2 and newer; older systems need the Universal C Runtime from the Visual C++ 2015-2022 Redistributable

The static musl build has no external library dependency. Windows 10 and newer already include the Universal C Runtime.

From source ​

bash
git clone nostr://danconwaydev.com/ngit
cd ngit
git checkout stable
cargo build --release

Then move ./target/release/ngit and ./target/release/git-remote-nostr onto your PATH.

Building against a private CA

If your git server or relay uses a certificate from an internal CA, build with --features native-tls-roots so ngit trusts your system certificate store.

Verify ​

Both commands must resolve:

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

If ngit works but git-remote-nostr doesn't, git clones will fail. See Troubleshooting.

Update ​

Check whether a signed release is ready without changing the installation:

bash
ngit update --check

For a standalone macOS or Linux installation made by the one-line installer, update both binaries together with:

bash
ngit update

The installer writes a receipt beside the binaries. That receipt is the safety boundary which lets ngit know it owns a standalone installation. In ngit 3.0.2, ngit update and the one-line installer can also upgrade Cargo installations using Cargo's default registry and default features. This preserves the install location, not custom source or feature selections. Nix, other package-manager, source, Windows self-updates, and older unreceipted standalone installations receive instructions for the appropriate installation method instead. You can also rerun the one-line installer above, or select --method standalone to install a separate downloaded copy. The installer warns if your terminal is still using another copy.

You can select an exact signed version, including an older release or a release candidate:

bash
ngit update <version>

The update is still anchored to ngit's signed repository state and verified release assets. See the generated ngit update reference for relay and automation options.

Next ​