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

For better security, download a NIP-07 browser extension like:

On mobile browsers: Mobile browsers don't support browser extensions. Install Nowser to sign via NIP-46/NIP-07, or use a remote signer (NIP-46) with a hardware device.

Once installed, the extension will automatically detect when you visit the login page and allow you to sign in securely.

2. Create or Import a Repository

You can create a new repository or import from GitHub/GitLab/Codeberg. There are three ways to get started:

📦 Option 1: Import Single Repository

Import an existing repository from GitHub, GitLab, or Codeberg:

  • Enter owner/repo (e.g., arbadacarbaYK/gittr)
  • Or provide a full URL: https://github.com/owner/repo
  • Files are automatically fetched and stored in your browser

➕ Option 2: Create Empty Repository

Create a new empty repository from scratch:

  • Enter a repository name
  • Click "Create Empty Repository"
  • Important: The repository will be empty until you push files via Git (see below)

📚 Option 3: Bulk Import from GitHub

Import multiple repositories at once from a GitHub user or organization:

  • Click "Bulk Import from GitHub"
  • Browse and select which repositories to import
  • You can import all or just specific ones

⚠️ Important: Getting Files Into Your Repository

For empty repositories created via web UI: After creating an empty repository, you need to push files to it before they appear in the web UI. The workflow is:

  1. Clone the repository: git clone [email protected]:<your-pubkey>/<repo-name>.git
  2. Add your files: Copy files into the cloned directory, or create new files
  3. Commit your changes: git add . && git commit -m "Initial commit"
  4. Push to the repository: git push origin main

Why this is necessary: The git-nostr-bridge stores repositories as bare Git repositories. Files only appear in the web UI after they've been committed and pushed via Git.

For imported repositories: Files are automatically fetched during import, so they appear immediately in the web UI.

3. Set Up Payments (Optional)

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

Managing Repositories

Creating Repositories

You can create repositories in three ways:

  • Import from GitHub/GitLab/Codeberg: Files are automatically fetched and stored in your browser
  • Create empty repository: Creates an empty repo that you must populate via Git CLI (clone, add files, commit, push)
  • Bulk import: Import multiple repositories at once from a GitHub user/organization

All repos are stored locally in your browser and can be pushed to Nostr for public access. Important: Empty repositories created via web UI will not show files until you push them via Git.

📖 Complete Workflow for Empty Repositories

After creating an empty repository via web UI:

  1. Set up SSH keys in Settings → SSH Keys (if not already done)
  2. Clone: git clone [email protected]:<your-pubkey>/<repo-name>.git
  3. Add files: Copy files into the cloned directory or create new files
  4. Commit: git add . && git commit -m "Initial commit"
  5. Push: git push origin main

Files will appear in the web UI after pushing. See Git Operations section for detailed instructions.

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 (link your GitHub identity via NIP-39 in Profile settings)
  • GitLab - Import from GitLab URLs (coming soon)

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

🔒 Private Repository Support

GitHub Private Repos: When you import a private GitHub repository, the privacy status is preserved locally. The repository will be marked as "Private" in gittr.space. Privacy is enforced via the maintainers tag (NIP-34 spec) and bridge access control.

  • NIP-34 Spec Compliance: Privacy is NOT encoded in NIP-34 event tags (per spec). The NIP-34 spec does not include public-read or public-write tags. Privacy is determined by the maintainers tag (which IS in the spec) and bridge-level access control.
  • Files Access: Files from private GitHub repos require GitHub authentication. Connect your GitHub account via OAuth (Settings → SSH Keys) to access private repo files.
  • Other Clients: Other NIP-34 clients can see repository events on relays (for discoverability), but file access is restricted to maintainers via the bridge. Clients that support the maintainers tag can identify private repos and enforce access control accordingly.
  • Access Control: Only users listed in the maintainers tag (or the repository owner) can access private repos. This is enforced at the bridge level for Git operations (SSH/HTTPS) and at the API level for file fetching.

🔗 Identity Mapping & Access Control

How Access Works: Access to private repositories is determined by your Nostr pubkey (npub), not your GitHub username. This means:

  • Owner: The repository owner (the Nostr pubkey that created/pushed the repo) has full access
  • Maintainers: Users whose Nostr pubkey (npub) is explicitly added as a maintainer in Repository Settings → Contributors
  • GitHub Identity: If you're a maintainer on GitHub but haven't linked your Nostr identity, you won't have access until the owner adds your npub

Why This Matters: When importing from GitHub, contributors are mapped to Nostr identities using:

  1. OAuth Mapping: If you've done GitHub OAuth, your GitHub username is linked to your Nostr pubkey in localStorage
  2. NIP-39 Claims: If you've published a Kind 0 event with ["i", "github:username"] tags, your identity is claimed on Nostr
  3. Manual Addition: The repository owner can manually add maintainers by their npub in Repository Settings

⚠️ Common Issue: "Access Denied" for Maintainers

If you're a maintainer on GitHub but can't access a private repo on gittr.space:

  • The repository owner needs to add your Nostr pubkey (npub) as a maintainer in Repository Settings → Contributors
  • Your GitHub username alone isn't enough - you need your npub explicitly added
  • This ensures security: only the owner can grant access, and it's tied to your Nostr identity, not just GitHub

💻 CLI & API Access

When accessing private repositories via Git CLI or API:

  • Git Clone: Requires SSH keys configured in Settings → SSH Keys. The bridge checks your pubkey against the repository's maintainers list.
  • Error Message: If access is denied, you'll see: fatal: permission denied for read operation with hints on how to get access.
  • API Endpoints: Private repo endpoints gracefully return null/404 for unauthorized users (no errors thrown).

Note: The same access control applies - you need your npub added as a maintainer by the owner, regardless of whether you access via web UI, CLI, or API.

⚠️ 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://git.gittr.space/<owner-pubkey>/repo-name.git

Read-only clones from our public mirrors (git.gittr.space, gitnostr.com, relay.ngit.dev, 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

  • 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)

How it works:

  • With SSH keys (added in Settings → SSH Keys): Automatically uses SSH for push/pull operations
  • Without SSH keys: Falls back to HTTPS (read-only or with credentials)

Once installed, git clone nostr://… works with or without SSH keys - git-remote-nostr automatically chooses the best option.

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 git.gittr.space automatically. Only small metadata files live inside the Nostr event; the real Git objects stay on the bridge.

📦 File Content During Push

Files are sourced from your browser's localStorage (from create/import workflow) or from the bridge API if missing. The push process does NOT fetch files from external sources (GitHub, GitLab, etc.).

If files are missing: Re-import the repository to load all files into localStorage before pushing.

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 →

Code Snippets (NIP-C0)

Select code in any file viewer to share it as a standalone snippet on Nostr. The action bar appears near your selection with options to copy a permalink or share as a snippet.

Mobile-friendly: Line numbers are hidden on mobile devices to avoid alignment issues, but all functionality is preserved. Code lines remain fully clickable for selection.

Share Code Snippets

Share code snippets from your repositories as standalone, discoverable events on Nostr.

How to Share:

  1. Open any file in a repository
  2. Select the code lines you want to share (click to select, Shift+click to extend)
  3. Click the "Share as snippet" button that appears
  4. Optionally add a description
  5. Click "Share to Nostr"

What Gets Shared:

  • The selected code (with syntax highlighting)
  • Language and file extension (auto-detected)
  • Optional description
  • Link back to source repository (NIP-34 format)

Using Snippets in Comments

Reference code snippets in issue and PR comments. Snippets will appear inline with syntax highlighting.

💡 How it works:

  1. Share a code snippet using the "Share as snippet" button
  2. Copy the snippet event ID (shown after sharing)
  3. Paste the event ID in a comment (as nostr:note1... or hex format)
  4. The snippet will automatically render inline with syntax highlighting

Snippet Features

  • Syntax Highlighting: Code is displayed with proper formatting
  • Copy Code: One-click copy button
  • Download: Download snippet as a file
  • Repository Link: Click to view the source repository
  • Discoverable: Snippets are searchable across the Nostr network

Learn more about NIP-C0:

📖 NIP-C0 Specification →

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.

📋 How PRs Are Organized

  • Sorted by creation time: PRs are displayed with the newest first, regardless of status changes
  • Aggregated from Nostr: PRs created by anyone (locally or on other clients) appear in the list automatically
  • Status tracking: Status changes (open → merged/closed) don't affect the chronological order
  • Real-time updates: New PRs and status changes from Nostr relays appear automatically

Issues

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

📋 How Issues Are Organized

  • Sorted by creation time: Issues are displayed with the newest first, regardless of status changes
  • Aggregated from Nostr: Issues created by anyone (locally or on other clients) appear in the list automatically
  • Status tracking: Status changes (open → closed) don't affect the chronological order
  • Real-time updates: New issues and status changes from Nostr relays appear automatically

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.

⚠️ Browser & Domain Isolation

Your data is stored separately for each browser and domain:

  • Different browsers (Chrome, Brave, Firefox) have separate storage
  • Different domains (localhost:3000 vs gittr.space) have separate storage
  • Repos, PRs, Issues, and edits are not shared between browsers/domains

If you're missing repos, PRs, or edits: They might be in a different browser or on a different domain. Use the Explore page to see all repos from Nostr (consistent across browsers).

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.