gitrepublic-web/docs/tutorial.md

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. Repository Settings
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:

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

Initial Setup

After creating your repository, you can:

1. Clone it locally:

   git clone https://{domain}/{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}/{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

1. Install a git credential helper (if not already installed):

   # For Linux/Mac
   git config --global credential.helper store
   

2. Configure git to use NIP-98:

   git config --global credential.https://{domain}.helper '!f() { echo "username=nostr"; echo "password=$(nostr-auth-token)"; }; f'
   

   Note: You may need a custom credential helper that generates NIP-98 auth tokens. Check the GitRepublic documentation for your specific setup.

3. Clone the private repository:

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

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

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}/{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. Review the PR and ensure all checks pass
2. Click "Merge" or change the status to "Applied"
3. The changes will be merged into the target branch

---

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 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}/{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}/{original-npub}/{original-repo}.git
   

2. Fetch and merge:

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

---

Repository Settings

Access repository settings by clicking "Settings" on your repository page.

Privacy Settings

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

Maintainer Management

Add maintainers who can:

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

To add a maintainer:

1. Go to Settings
2. Enter the maintainer's npub
3. Click "Add Maintainer"

To remove a maintainer:

1. Go to Settings
2. Find the maintainer in the list
3. Click "Remove"

Repository Description

Update your repository description:

1. Go to Settings
2. Edit the description field
3. Save changes

Clone URLs

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

1. Go to Settings
2. Add clone URLs (one per line)
3. Save changes

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

Ownership Transfer

Transfer repository ownership to another user:

1. Go to Settings
2. Enter the new owner's npub
3. Confirm the transfer

Important: Ownership transfers are permanent and create a chain of ownership events. The new owner will have full control.

---

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

---

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 1621: Issue
• Kind 1641: Ownership transfer

See the NIP-34 specification 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! 🚀