silberengel
/
gitrepublic-web
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
124 Commits
1 Branch
0 Tags
13 MiB
 
 
 
 
 
Tree: d33bf8e23d
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd33bf8e23d'
${ noResults }
gitrepublic-web/docs/tutorial.md

28 KiB
Raw Blame History

GitRepublic Tutorial & Walkthrough

Welcome to GitRepublic! This comprehensive guide will walk you through everything you need to know to get started with decentralized git hosting on Nostr.

Table of Contents

  1. What is GitRepublic?
  2. Getting Started
  3. Creating Your First Repository
  4. Cloning Repositories
  5. Making Changes and Pushing
  6. Pull Requests
  7. Issues
  8. Forking Repositories
  9. Updating Repository Information
  10. Collaboration Features
  11. Best Practices
  12. Troubleshooting

What is GitRepublic?

GitRepublic is a decentralized git hosting platform built on Nostr. Unlike traditional git hosting services, GitRepublic:

  • No central authority: Your repositories are announced on Nostr relays, making them truly decentralized
  • Nostr-based authentication: Uses NIP-07 (browser extensions) and NIP-98 (HTTP authentication) for secure access
  • Full control: You own your repositories and can transfer ownership, manage maintainers, and control access
  • Open collaboration: Create pull requests, issues, and collaborate with others using Nostr events

Key Concepts

  • NIP-34: The Nostr Improvement Proposal that defines how repositories are announced and managed
  • NIP-07: Browser extension authentication (like Alby or nos2x)
  • NIP-98: HTTP authentication for git operations (clone, push, pull)
  • Repository Announcements: Nostr events (kind 30617) that announce your repository to the network
  • Ownership Transfer: Chain of ownership events (kind 1641) that prove repository ownership

Getting Started

Prerequisites

Before you begin, you'll need:

  1. A Nostr key pair: You can generate one using a NIP-07 browser extension
  2. NIP-07 Extension: Install Alby or nos2x in your browser
  3. Git installed: Make sure you have git installed on your system
  4. Access to GitRepublic: Visit the GitRepublic instance you want to use

Step 1: Install NIP-07 Extension

  1. Install a Nostr browser extension:

    • Alby: getalby.com
    • nos2x: Available for Chrome/Firefox

  2. Create or import your Nostr key pair in the extension

  3. Make sure the extension is active and unlocked

Step 2: Connect to GitRepublic

  1. Visit the GitRepublic homepage
  2. Click the Login button in the top right
  3. Approve the connection request in your NIP-07 extension
  4. You should now see your user badge in the header

Creating Your First Repository

Using the Web Interface

  1. Navigate to Sign Up: Click "Sign Up" in the navigation menu

  2. Fill in Repository Details:

    • Repository Name: Choose a unique name (e.g., my-awesome-project)
    • Description: Add a description of what your repository does
    • Clone URLs (optional): If you're migrating from another git host, add the clone URLs here
    • Private (optional): Check this if you want a private repository

  3. Create Repository: Click the create button

  4. What Happens Next:

    • GitRepublic creates a Nostr event announcing your repository
    • A bare git repository is automatically provisioned
    • You'll be redirected to your new repository page

Repository URL Structure

Your repository will be accessible at:

https://{domain}/repos/{your-npub}/{repository-name}

For git operations, you can use any of these paths:

https://{domain}/api/git/{your-npub}/{repository-name}.git  # Recommended
https://{domain}/repos/{your-npub}/{repository-name}.git
https://{domain}/{your-npub}/{repository-name}.git

Note: The /api/git/ path is recommended for best compatibility with commit signing hooks.

Initial Setup

After creating your repository, you can:

  1. Clone it locally:

    git clone https://{domain}/api/git/{your-npub}/{repository-name}.git
cd {repository-name}

  2. Add your first files:

    echo "# My Awesome Project" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Cloning Repositories

Public Repositories

Anyone can clone public repositories without authentication:

git clone https://{domain}/api/git/{owner-npub}/{repository-name}.git
cd {repository-name}

Private Repositories

Private repositories require authentication. You'll need to set up NIP-98 authentication.

Setting Up NIP-98 Authentication

For command-line git operations, you need to install the GitRepublic CLI which provides:

  1. Credential Helper: Automatically generates NIP-98 authentication tokens for git operations
  2. Commit Signing Hook: Automatically signs commits for GitRepublic repositories

Quick Setup:

  1. Install the CLI:

    npm install -g gitrepublic-cli

  2. Set your Nostr private key:

    export NOSTRGIT_SECRET_KEY="nsec1..."

  3. Run the setup script:

    gitrepublic-setup

This automatically configures the credential helper and commit signing hook. See the README for complete setup instructions.

  1. Clone the private repository:

    git clone https://{domain}/api/git/{owner-npub}/{repository-name}.git

    When prompted, the credential helper will automatically generate and use a NIP-98 authentication token.

Note: For command-line git operations, you'll need to install the GitRepublic CLI via npm install -g gitrepublic-cli and set up the credential helper. See the README for complete setup instructions.

Cloning from Multiple Remotes

If a repository has multiple clone URLs configured, GitRepublic will automatically sync changes to all remotes when you push. You can see all clone URLs on the repository page.

Making Changes and Pushing

Basic Workflow

  1. Make changes to your files:

    echo "New feature" >> README.md

  2. Stage your changes:

    git add README.md

  3. Commit your changes:

    git commit -m "Add new feature"

  4. Push to GitRepublic:

    git push origin main

Authentication for Push

When you push, GitRepublic will:

  1. Verify your NIP-98 authentication token
  2. Check that you're the repository owner or a maintainer
  3. Verify the repository size limit (2 GB maximum)
  4. Process your push
  5. Automatically sync to other remotes (if configured)

Branch Management

Creating a New Branch

git checkout -b feature/new-feature
# Make changes
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

Viewing Branches

You can view all branches:

  • On the repository web page
  • Using the API: GET /api/repos/{npub}/{repo}/branches

Creating Branches via Web UI

  1. Navigate to your repository
  2. Click "Create Branch"
  3. Enter branch name and select the source branch
  4. Click "Create"

Tags

Creating a Tag

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Creating Tags via Web UI

  1. Navigate to your repository
  2. Click "Create Tag"
  3. Enter tag name, select commit, and add a message
  4. Click "Create"

Pull Requests

Pull requests (PRs) allow you to propose changes to a repository. They're created as Nostr events (kind 1618) and can be reviewed, commented on, and merged.

Creating a Pull Request

Method 1: Via Web Interface

  1. Fork the repository (if you don't have write access)
  2. Make your changes in your fork
  3. Push your changes to a branch
  4. Navigate to the original repository
  5. Click "Create Pull Request"
  6. Fill in the details:
    • Source repository and branch
    • Target repository and branch
    • Title and description
  7. Submit the PR

Method 2: Using Git and Nostr

  1. Fork and clone the repository:

    git clone https://{domain}/api/git/{owner-npub}/{repo}.git
cd {repo}

  2. Create a feature branch:

    git checkout -b feature/my-feature

  3. Make your changes and push:

    # Make changes
git add .
git commit -m "Add new feature"
git push origin feature/my-feature

  4. Create a PR event using a Nostr client or the web interface

Reviewing Pull Requests

  1. Navigate to the repository
  2. Click on "Pull Requests"
  3. Select a PR to review
  4. Review the changes in the diff view
  5. Add comments on specific lines or sections
  6. Approve or request changes

PR Status

Pull requests can have the following statuses:

  • Open: The PR is active and ready for review
  • Applied/Merged: The PR has been merged into the target branch
  • Closed: The PR was closed without merging
  • Draft: The PR is still a work in progress

Merging Pull Requests

Only repository owners and maintainers can merge PRs:

  1. Open the PR detail view by clicking on a PR
  2. Review the changes in the diff view
  3. Click "Merge" button
  4. Select target branch (default: main)
  5. Optionally add a merge message
  6. Click "Merge" to:
    • Create a merge commit in the target branch
    • Update PR status to "merged" (kind 1631)
    • Include merge commit ID in the status event

Managing PR Status

Repository owners and maintainers can manage PR status:

  • Close PR: Click "Close" button to mark PR as closed (kind 1632)
  • Reopen PR: Click "Reopen" button on a closed PR to reopen it (kind 1630)
  • Mark as Draft: Click "Mark as Draft" to mark PR as draft (kind 1633)

PR Updates (Kind 1619)

Only the PR author can update their PR:

  • PR updates change the tip commit of the PR
  • Use this when you've pushed new commits to your branch
  • The update creates a kind 1619 event with the new commit ID

Patches

Patches (kind 1617) are an alternative to pull requests for proposing changes to a repository. They're particularly useful for smaller changes or when you want to send code changes directly without creating a full pull request.

Patches vs. Pull Requests

When to use Patches:

  • Small changes: Each patch event should be under 60KB (per NIP-34 specification)
  • Simple fixes: Bug fixes, typo corrections, or small feature additions
  • Direct code submission: When you want to send code changes directly without maintaining a fork
  • Email-style workflow: Similar to traditional git email-based patch workflows

When to use Pull Requests:

  • Large changes: Changes that exceed 60KB per event
  • Complex features: Multi-file changes that need discussion and review
  • Ongoing collaboration: When you need to iterate on changes with maintainers
  • Branch-based workflow: When you're working with forks and branches

Key Differences

Feature Patches Pull Requests
Size Limit Under 60KB per event No strict limit
Format Git format-patch output Markdown description + commit reference
Workflow Email-style, sequential Branch-based, iterative
Series Support Yes (linked via NIP-10 reply tags) Yes (via PR updates)
Content Full patch content in event Reference to commits in clone URL
Use Case Small, self-contained changes Large, complex changes

Creating a Patch

wPatches are created as Nostr events (kind 1617). The patch content is embedded directly in the event, making it easy to share and review without requiring access to a git repository.

Via Web Interface

  1. Navigate to the repository you want to contribute to
  2. Click the repository menu (three dots) and select "Create Patch"
  3. Fill in the patch details:
    • Subject (optional): A brief title for your patch
    • Patch Content: Enter your patch content (can be in git format-patch format, but any patch format is acceptable)
  4. Submit the patch - it will be published as a Nostr event (kind 1617) to the repository's relays

Patch Content Format

The patch content can be in any format that describes code changes. Common formats include:

  • Git format-patch output: Standard git patch format
  • Unified diff format: git diff output
  • Plain text description: For simple changes, you can describe the changes in plain text

The key advantage of event-based patches is that they're self-contained Nostr events that can be discovered, shared, and reviewed without requiring access to the original git repository.

Patch Series

For multiple related patches, you can create a patch series:

  1. First patch: Marked with t tag "root"
  2. Subsequent patches: Include NIP-10 e reply tags pointing to the previous patch
  3. Patch revisions: If you need to revise a patch, mark the first revision with t tag "root-revision" and link to the original root patch

Patch Status

Like pull requests, patches can have status events:

  • Open: The patch is active and ready for review
  • Applied/Merged: The patch has been applied to the repository
  • Closed: The patch was closed without applying
  • Draft: The patch is still a work in progress

Applying Patches

Repository owners and maintainers can apply patches from Nostr events:

  1. Review the patch event - patches are stored as Nostr events (kind 1617) and can be found on relays
  2. Extract the patch content from the event content field
  3. Apply the patch using git (if in git format): 
    # If the patch content is in git format-patch format, save it to a file and apply:
echo "<patch-content-from-event>" > patch.patch
git am patch.patch
    Or manually apply the changes if the patch is in a different format
  4. Create a status event (kind 1631) marking the patch as applied, referencing the patch event ID
  5. Push the changes to the repository

The status event creates a permanent record that the patch was applied, linking the patch event to the resulting commits.

Issues

Issues (kind 1621) allow you to track bugs, feature requests, and other tasks related to your repository.

Creating an Issue

  1. Navigate to your repository
  2. Click "Issues" in the repository menu
  3. Click "Create Issue"
  4. Fill in the details:
    • Title
    • Description
    • Labels (optional)
  5. Submit the issue

Issue Status

Issues can have the following statuses:

  • Open: The issue is active and needs attention
  • Resolved: The issue has been fixed or addressed
  • Closed: The issue was closed (e.g., duplicate, won't fix)
  • Draft: The issue is still being written

Managing Issue Status

Repository owners, maintainers, and issue authors can update issue status:

  • Close Issue: Click "Close" button to mark issue as closed (kind 1632)
  • Resolve Issue: Click "Resolve" button to mark issue as resolved (kind 1631)
  • Reopen Issue: Click "Reopen" button on a closed or resolved issue to reopen it (kind 1630)
  • Mark as Draft: Mark issue as draft (kind 1633)

Managing Issues

  • Assign issues to maintainers
  • Add comments to discuss solutions
  • Link issues to PRs by referencing them in PR descriptions
  • Close issues when they're resolved

Forking Repositories

Forking creates your own copy of a repository that you can modify independently.

How to Fork

  1. Navigate to the repository you want to fork
  2. Click the "Fork" button
  3. GitRepublic will:
    • Create a copy of the repository under your account
    • Create a new NIP-34 announcement for your fork
    • Set you as the owner of the fork
    • Add a reference to the original repository

Working with Forks

After forking:

  1. Clone your fork:

    git clone https://{domain}/api/git/{your-npub}/{fork-name}.git

  2. Make changes in your fork

  3. Push changes:

    git push origin main

  4. Create a pull request back to the original repository (if you want to contribute)

Syncing with Upstream

To keep your fork up to date with the original repository:

  1. Add the original as a remote:

    git remote add upstream https://{domain}/api/git/{original-npub}/{original-repo}.git

  2. Fetch and merge:

    git fetch upstream
git merge upstream/main
git push origin main

Updating Repository Information

To update your repository information, navigate to the signup page with your repository details pre-filled.

Accessing the Update Form

  1. Navigate to your repository page
  2. Click "Settings" (if you're the owner or a maintainer)
  3. You'll be redirected to the signup page with all current repository information pre-filled

Privacy Settings

  • Public: Anyone can view and clone your repository
  • Private: Only owners and maintainers can access

You can change the privacy setting by checking or unchecking the "Private Repository" option in the update form.

Maintainer Management

Add maintainers who can:

  • Push to the repository
  • Merge pull requests
  • Manage issues
  • Update repository information

To add a maintainer:

  1. Access the update form (via Settings link)
  2. Enter the maintainer's npub in the maintainers field
  3. Click "Add Maintainer" to add additional maintainer fields
  4. Save changes

To remove a maintainer:

  1. Access the update form
  2. Remove the maintainer's npub from the maintainers field
  3. Save changes

Repository Description

Update your repository description:

  1. Access the update form
  2. Edit the description field
  3. Save changes

Clone URLs

Add multiple clone URLs to sync your repository to other git hosts:

  1. Access the update form
  2. Add clone URLs (one per field)
  3. Save changes

When you push, GitRepublic will automatically sync to all configured remotes.

Ownership Transfer

Transfer repository ownership to another user using the transfer workflow:

  1. Initiate Transfer: On your repository page, click "Transfer Ownership"
  2. Enter New Owner: Provide the new owner's npub
  3. Sign and Publish: The transfer event (kind 1641) is signed and published to Nostr relays
  4. Save to Repository: The transfer event is saved to nostr/repo-events.jsonl in your repository for offline papertrail
  5. New Owner Notification: The new owner will be notified when they log into GitRepublic web
  6. Complete Transfer: The new owner completes the transfer by publishing a new repository announcement (kind 30617)
  7. Verification: The new announcement is saved to the repository, and the transfer is complete

Important: Ownership transfers are permanent and create a chain of ownership events. The new owner will have full control. Both the transfer event and the new repository announcement are published to relays and saved to nostr/repo-events.jsonl in the repository for both online and offline papertrail.

Collaboration Features

Code Highlights

Highlight specific code sections in pull requests:

  1. Select code in the PR diff view
  2. Click "Highlight"
  3. Add a comment explaining the highlight
  4. Others can comment on your highlights

Comments

Comment on:

  • Pull requests
  • Issues
  • Code highlights
  • Specific lines in diffs

Comments are threaded and use Nostr events (kind 1111) for persistence.

Notifications

GitRepublic uses Nostr events for notifications. You can:

  • Subscribe to repository events
  • Get notified of new PRs, issues, and comments
  • Track changes using your Nostr client

Best Practices

Repository Organization

  1. Use descriptive names: Choose clear, descriptive repository names
  2. Write good READMEs: Include installation instructions, usage examples, and contribution guidelines
  3. Use tags for releases: Tag important versions (e.g., v1.0.0)
  4. Keep repositories focused: One repository per project or component

Commit Messages

Write clear, descriptive commit messages:

# Good
git commit -m "Add user authentication feature"

# Better
git commit -m "Add user authentication with NIP-07 support

- Implement NIP-07 browser extension authentication
- Add login/logout functionality
- Update UI to show user badge when logged in"

Branch Strategy

  • main/master: Production-ready code
  • feature/: New features
  • bugfix/: Bug fixes
  • hotfix/: Urgent production fixes

Pull Request Guidelines

  1. Keep PRs focused: One feature or fix per PR
  2. Write clear descriptions: Explain what and why, not just what
  3. Link related issues: Reference issues in PR descriptions
  4. Request reviews: Ask maintainers to review your PRs
  5. Respond to feedback: Address review comments promptly

Security

  1. Keep your keys secure: Never share your nsec (private key)
  2. Use NIP-07 extensions: Don't enter keys directly in web forms
  3. Review maintainers: Only add trusted users as maintainers
  4. Monitor your repositories: Check for unexpected changes

Troubleshooting

Authentication Issues

Problem: Can't push to repository

Solutions:

  • Verify you're logged in with NIP-07
  • Check that you're the owner or a maintainer
  • Ensure your NIP-98 authentication is configured correctly
  • Check repository privacy settings

Clone Fails

Problem: Can't clone a repository

Solutions:

  • Verify the repository URL is correct
  • Check if the repository is private (requires authentication)
  • Ensure you have network access to the GitRepublic instance
  • Try cloning with verbose output: git clone -v {url}

Push Fails

Problem: Push is rejected

Solutions:

  • Check repository size limit (2 GB maximum)
  • Verify you have write permissions
  • Ensure your branch is up to date: git pull origin main
  • Check for branch protection rules

Repository Not Found

Problem: Repository doesn't appear after creation

Solutions:

  • Wait a few moments for auto-provisioning
  • Refresh the page
  • Check that the NIP-34 announcement was published
  • Verify you're looking at the correct domain

Sync Issues

Problem: Changes not syncing to other remotes

Solutions:

  • Verify clone URLs are correct in repository settings
  • Check network connectivity to remote git hosts
  • Review server logs for sync errors
  • Manually push to remotes if needed

User Profiles and Payment Targets

GitRepublic displays full user profiles with support for payment targets using NIP-A3 (kind 10133).

Viewing User Profiles

  1. Navigate to a user's profile page: /users/{npub}
  2. View their repositories, profile information, and payment targets
  3. Profiles support both old JSON format (in content) and new tags format

Payment Targets (NIP-A3)

Payment targets allow users to specify how they want to receive payments using the payto:// URI scheme (RFC-8905).

Supported Payment Types

  • Lightning: Lightning Network addresses (e.g., user@wallet.example.com)
  • Bitcoin: Bitcoin addresses
  • Ethereum: Ethereum addresses
  • Nano: Nano addresses
  • Monero: Monero addresses
  • And more (see NIP-A3 documentation)

How Payment Targets Work

GitRepublic merges payment information from multiple sources:

  1. NIP-01 (kind 0): Lightning addresses from lud16 tags or JSON lud16 field
  2. NIP-A3 (kind 10133): All payment targets from payto tags

The system:

  • Normalizes addresses (lowercase) for deduplication
  • Merges lightning addresses from both sources
  • Displays all payment targets with payto:// URIs
  • Provides copy buttons for easy sharing

Creating Payment Target Events

To add payment targets to your profile, publish a kind 10133 event:

{
  "kind": 10133,
  "content": "",
  "tags": [
    ["payto", "lightning", "user@wallet.example.com"],
    ["payto", "bitcoin", "bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k"]
  ],
  "created_at": 1234567890
}

API Access

Fetch user profiles with payment targets via the API:

GET /api/users/{npub}/profile

Response includes:

  • Full profile event (kind 0)
  • Payment targets array with payto:// URIs
  • Payment event (kind 10133) if available

CLI Access

The GitRepublic CLI automatically fetches payment targets when fetching profiles:

gitrep profile fetch npub1...

See NIP-A3 documentation for complete details.

Advanced Topics

NIP-34 Specification

GitRepublic implements NIP-34 for repository announcements. Key event types:

  • Kind 30617: Repository announcement
  • Kind 30618: Repository state
  • Kind 1617: Git patch
  • Kind 1618: Pull request
  • Kind 1619: Pull request update
  • Kind 1621: Issue
  • Kind 1630-1633: Status events (open, applied/merged, closed, draft)
  • Kind 1641: Ownership transfer

See the NIP-34 documentation for full details.

GRASP Protocol Support

GitRepublic supports the GRASP (Git Repository Announcement and Synchronization Protocol) for interoperability with other git hosting services built on Nostr.

What is GRASP?

GRASP is a protocol that extends NIP-34 to provide a standardized way for git repositories to be announced, synchronized, and managed across different hosting providers. GRASP servers implement additional NIP-34 event kinds (such as patches, pull request updates, repository state tracking, and user grasp lists) that enable more advanced collaboration features.

How GitRepublic Supports GRASP:

While GitRepublic is directly git-based and doesn't require all NIP-34 features to function, we fully support repositories hosted on GRASP servers:

  1. Multi-Remote Synchronization: When you create a repository announcement with multiple clone URLs (including GRASP server URLs), GitRepublic automatically:

    • Syncs from GRASP servers when provisioning new repositories
    • Pushes changes to all configured remotes (including GRASP servers) after each push
    • Keeps your repository synchronized across all hosting providers

  2. On-Demand Repository Fetching: If a repository is announced on Nostr but not yet provisioned locally, GitRepublic can:

    • Automatically fetch the repository from any configured clone URL (including GRASP servers)
    • Display and serve repositories hosted entirely on GRASP servers
    • Clone repositories from GRASP servers when users access them

  3. Interoperability: You can:

    • Use GitRepublic as your primary git host while syncing to GRASP servers
    • Host repositories on GRASP servers and have them accessible through GitRepublic
    • Migrate repositories between GRASP servers and GitRepublic seamlessly

Example: Using GRASP Servers

When creating a repository, you can add GRASP server URLs as clone URLs:

https://grasp.example.com/user/repo.git

GitRepublic will automatically:

  • Clone from the GRASP server if the repo doesn't exist locally
  • Push all changes to the GRASP server after each push
  • Keep both repositories in sync

This means you can use GitRepublic's direct git-based workflow while maintaining compatibility with GRASP-based services that use patches, PR updates, and other advanced NIP-34 features.

For more information about the GRASP protocol, see the GRASP Protocol Documentation.

NIP-98 HTTP Authentication

Git operations use NIP-98 for authentication:

  1. Client creates an ephemeral event (kind 27235)
  2. Event includes request URL, method, and payload hash
  3. Client signs event and includes in Authorization header
  4. Server verifies signature and permissions

Relay Configuration

GitRepublic uses Nostr relays to:

  • Publish repository announcements
  • Fetch repository metadata
  • Sync pull requests and issues
  • Track ownership transfers

Default relays are configured, but you can use custom relays if needed.

Getting Help

  • Documentation: Check this tutorial and the NIP-34 specification
  • Issues: Report bugs or request features via GitHub issues (if the instance has a GitHub repo)
  • Community: Join Nostr communities to discuss GitRepublic
  • Support: Contact the GitRepublic instance administrator

Conclusion

Congratulations! You now know how to use GitRepublic for decentralized git hosting. Remember:

  • GitRepublic is built on Nostr, making it truly decentralized
  • You have full control over your repositories
  • Collaboration happens through Nostr events
  • Security is handled via NIP-07 and NIP-98

Happy coding!