NostrGit

Help & Documentation

Everything you need to know about using gittr.space - Git over Nostr with Bitcoin incentives

Quick Start

Development

Settings

Getting Started

1. Login with NIP-07

Install a NIP-07 browser extension (like Alby or nos2x) and log in to access all features.

2. Create or Import a Repository

Click "Create repository" to start a new repo, or "Import" to bring in an existing GitHub repository.

3. Set Up Payments (Optional)

Go to Settings → Payments to configure LNbits, LNURL, or NWC for receiving zaps and bounties.

Managing Repositories

Creating Repositories

Create new repositories from scratch or import from GitHub. All repos are stored locally in your browser and can be pushed to Nostr for public access.

Repository Status

  • Local - Only exists on your device
  • Pushing... - Currently being published to Nostr
  • Live on Nostr - Published and visible to others
  • Live (Unpushed Edits) - Has local changes not yet published
  • Push Failed - Publication attempt failed

File Management

View, edit, and delete files directly in the browser. Use the fuzzy file finder (Cmd/Ctrl+P) to quickly navigate large repositories.

File Sources & NIP-34 Architecture

gittr.space follows the NIP-34 architecture for file storage. Files are stored on git servers, not in Nostr events. The repository's "About" sidebar shows where files come from:

  • 📦 Embedded - Files stored directly in Nostr event (legacy repos)
  • ⚡ git-nostr-bridge - Files stored on decentralized git server
  • 🐙 GitHub - Files fetched from GitHub API
  • 🦊 GitLab - Files fetched from GitLab API

This architecture ensures files are stored efficiently and can be fetched from multiple sources for redundancy.

Importing Repositories

You can import repositories from:

  • GitHub - Single repo or bulk import via OAuth
  • GitLab - Import from GitLab URLs (coming soon)

Imported repos maintain a link to their source (sourceUrl) and fetch files from the original git server.

⚠️ 4 MB Import Limit

Next.js API routes hard-cap responses at ~4 MB. When importing we fetch every file (including releases/binaries), so very large repos will fail with “Repository is too large”. Remove heavy artifacts (release archives, media, build outputs) or import a slimmer subset before retrying.

Git Operations

Clone a Repository

gittr.space repositories support multiple clone URL formats:

Option A: SSH (Standard Git - Recommended)

git clone [email protected]:npub1.../repo-name.git

Requires SSH keys (Settings → SSH Keys). Works out of the box with any Git client.

Option B: HTTPS (GRASP git servers)

git clone https://relay.ngit.dev/<owner-pubkey>/repo-name.git

Read-only clones from our public mirrors (relay.ngit.dev, gitnostr.com, ngit-relay.nostrver.se, ...). Great for CI/CD or quick testing.

Option C: nostr:// Protocol (Ecosystem Standard)

git clone nostr://[email protected]/repo-name

Requires git-remote-nostr. This helper translates nostr:// URLs into standard Git fetches and is used by other NIP-34 clients.

Install git-remote-nostr (Nov 2025)

  • macOS/Linux: pip install git-remote-nostr (Python 3.10+)
  • or build from source: github.com/aljazceru/git-remote-nostr
  • Add to PATH so Git can find the helper (verify with which git-remote-nostr)

Once installed, git clone nostr://… works exactly like GitHub URLs.

SSH, HTTPS, and nostr:// clone URLs all ship inside every NIP-34 repository event. Pick whichever matches your workflow.

Supported Git Commands

Day-to-day

git pull / git fetchgit checkout <branch>git statusgit add / git commit

Publishing

Use the Push to Nostr button in the repo UI. We publish the NIP‑34 event and automatically sync your repo to our git bridge so other clients can clone it immediately.

CLI fan? You can still run git push origin main; it hits the same bridge endpoint.

Branches & Tags

git branch -a / git switch -cgit tag v1.2.3

Releases and tags show up instantly in the UI.

Troubleshooting

git remote -vgit config --listgit log --oneline

Push to Nostr

After making local changes, click "Push to Nostr" in your repository settings to publish updates.

We sign the NIP‑34 event, publish it to your relays, and sync the Git repo to relay.ngit.dev/gittr.space automatically. Only small metadata files live inside the Nostr event; the real Git objects stay on the bridge.

SSH Keys

Manage your SSH keys in Settings → SSH Keys. You'll need these for Git operations over SSH.

For complete documentation on SSH and Git operations:

📖 SSH & Git Access Guide →

Payments & Bounties

Zaps

Zap repositories to support contributors. Zaps are split automatically based on contributor weights.

💬 Payment Messages:

All zaps and bounties automatically include a payment message with your username, "via gittr.space", and bolt emojis (⚡⚡). This helps recipients identify where the payment came from. The message format is: {username} via gittr.space ⚡⚡ (max 160 characters).

  • Zaps: The message is included in the invoice comment field (visible to the recipient)
  • Bounties: The message is included in the withdraw link title (visible when claiming the bounty)
  • Your username is automatically fetched from your Nostr profile (Kind 0 metadata)

Bounties

Anyone can fund issues with bounties to incentivize contributions. Bounties use LNURL-withdraw links created from the bounty creator's LNbits wallet. The funds are reserved in the creator's wallet and will be deducted when the PR author claims the withdraw link.

⚠️ Important Requirements:

  • Bounty Creator: Must have LNbits sending wallet configured in Settings → Account
  • Bounty Creator: Must ensure sufficient balance remains in wallet until PR author claims the withdraw link
  • PR Author: Must have a valid Nostr pubkey (not a GitHub username)
  • PR Author: Must have a Lightning address (lud16 or lnurl) in their Nostr profile (Kind 0 metadata)

Bounty Flow:

  1. Bounty Creation: Anyone can create a bounty on any issue. The system checks if the creator has LNbits configured. If not, they're prompted to set it up in Settings → Account.
  2. Withdraw Link Creation: When a bounty is created, an LNURL-withdraw link is generated from the bounty creator's LNbits wallet. The funds are reserved (not immediately deducted) and remain in the creator's wallet.
  3. PR Creation: A developer creates a PR fixing the issue and links it to the issue number.
  4. PR Merge: Only the repo owner can merge PRs. When they merge a PR linked to an issue with a bounty, the withdraw link is released to the PR author.
  5. Bounty Claim: The PR author receives the withdraw link and can claim the bounty. When they claim it, the funds are deducted from the bounty creator's LNbits wallet and sent to the PR author's Lightning address (from their Nostr profile).
  6. Issue Closed Without PR: If an issue with a bounty is closed without a linked PR (e.g., the feature already exists, duplicate issue, etc.), the bounty withdraw link is automatically deleted and the bounty is cancelled. The bounty creator will be notified of the cancellation.

🔒 Bounty Protection & Trust Model:

  • Bounty Deletion Prevention: If a PR is linked to an issue with a bounty, the bounty cannot be deleted even if the issue is closed. This protects developers who are working on the fix.
  • Trust Model: We trust the repo owner/maintainer to verify that a merged PR actually fixes the issue. When a repo owner merges a PR linked to a bounty, they are attesting that the PR resolves the issue. This is a reasonable trust model - the repo owner has the most context about whether a fix is valid.
  • Fraud Prevention: If you don't trust a repo owner, don't create bounties on their repos. The system relies on the repo owner's judgment when merging PRs.
  • Bounty Cancellation: Bounties are automatically cancelled (withdraw link deleted) when an issue is closed without a PR. The bounty creator is notified via Nostr DM and/or Telegram (if enabled).

Bounty Flow Diagram:

Bounty statuses:

  • Pending - Bounty amount set but withdraw link not yet created
  • Paid - Withdraw link created and ready (funds reserved in bounty creator's wallet)
  • Released - Withdraw link released to PR author (they can claim it)
  • Cancelled - Bounty was cancelled (issue closed without PR, withdraw link deleted)
  • Offline - Payment state cannot be tracked

Key Points:

  • Bounties use withdraw links, not direct payments. The funds stay in the creator's wallet until claimed.
  • The bounty creator must ensure their LNbits wallet has sufficient balance until the PR author claims the withdraw link.
  • No account credentials are stored on the platform - everything uses the creator's local LNbits configuration.
  • The PR author's Lightning address is fetched from their Nostr profile (Kind 0 metadata), looking for lud16 or lnurl fields.
  • If the PR author doesn't have a Lightning address in their Nostr profile, the bounty cannot be claimed.

Bounty Hunt

Visit the Bounty Hunt page to discover funded issues across all repositories.

Notifications

Configure Notifications

Go to Settings → Notifications to set up:

  • Nostr DMs - Receive encrypted direct messages on Nostr
  • Telegram - Get notifications via Telegram DMs. Configure your Telegram User ID to receive private notifications for PRs, issues, and bounties.

Bounty announcements are also posted to the public @gittrspace channel.

Notification Events

You can enable/disable notifications for:

  • New issue in watched repos - When someone opens an issue in a repository you're watching
  • Comments on issues I opened/participate - When someone comments on an issue you created or are assigned to
  • New pull request in watched repos - When someone opens a PR in a repository you're watching
  • Reviews requested or comments on my PRs - When someone requests your review or comments on your PR
  • My PR merged - When your pull request is merged
  • I am @mentioned - When someone mentions you in a comment or description
  • My Bounties - When a bounty is funded on an issue you created (you'll be notified about the bounty amount)
  • Bounty released to me - When a bounty withdraw link is released to you after a PR you created is merged

Default Settings: Most notifications are disabled by default to reduce noise. The recommended settings (enabled by default) are: New issues, Issue comments, New PRs, PR reviews, PR merges, Mentions, My Bounties, and Bounty releases.

Important: Changes to notification preferences are not active until you click "SAVE NOW". Make sure to save your preferences after making changes.

Bounty Notifications

Bounty notifications are sent to:

  • Issue Owner (My Bounties): When someone funds a bounty on your issue, you'll receive a notification via Nostr DM and/or Telegram (if enabled) with the bounty amount and issue details.
  • PR Author (Bounty released to me): When a PR you created is merged and linked to an issue with a bounty, you'll receive a notification that the bounty withdraw link has been released to you. The notification includes the bounty amount and instructions on how to claim it.
  • Bounty Creator (Bounty cancelled): When an issue with your bounty is closed without a PR, you'll receive a notification that the bounty was cancelled and the withdraw link was deleted. This helps you know that your funds are no longer reserved.

Bounty announcements are also automatically posted to the public @gittrspace Telegram channel, regardless of your notification preferences.

Collaboration

Pull Requests

Create PRs to propose changes. Reviewers can approve, request changes, or merge PRs.

Issues

Track bugs, feature requests, and discussions. Add bounties to incentivize solutions.

Contributors

Link your GitHub profile in Settings to show your profile picture as a contributor icon.

Security & Privacy

Local Storage

All your data (repos, keys, settings) is stored locally in your browser. It never leaves your device unless you explicitly push to Nostr.

Encrypted Keys

Your Nostr private key and payment credentials are encrypted with a password you set. Enable encryption in Settings → Security.

Public vs Private

Repositories default to public when pushed to Nostr. You can set them to private in repository settings.

Additional Resources

Need More Help?

If you have questions or encounter issues, please check the GitHub repository or open an issue.