🌿 SuiGit - Decentralized GitHub on Sui Blockchain

╔════════════════════════════════════════════════════════╗
║                                                        ║
║   ███████╗██╗   ██╗██╗ ██████╗ ██╗████████╗            ║
║   ██╔════╝██║   ██║██║██╔════╝ ██║╚══██╔══╝            ║
║   ███████╗██║   ██║██║██║  ███╗██║   ██║               ║
║   ╚════██║██║   ██║██║██║   ██║██║   ██║               ║
║   ███████║╚██████╔╝██║╚██████╔╝██║   ██║               ║
║   ╚══════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝   ╚═╝               ║
║                                                        ║
║        Decentralized GitHub on Sui Blockchain          ║
║                                                        ║
║   🌿 Repositories • 🔐 Privacy • 🚀 Decentralized       ║
║                                                        ║
╚════════════════════════════════════════════════════════╝

🌿 SuiGit - Decentralized GitHub on Sui Blockchain

Version Control Without Intermediaries. Pure Decentralization.

A fully decentralized GitHub alternative built on Sui blockchain with Walrus storage. No central servers. No account lockdowns. No platform dependencies. Just you, your code, and blockchain.

🎯 The Problem We Solve

Traditional GitHub	SuiGit
❌ Centralized (GitHub owns it)	✅ Decentralized (You control it)
❌ Account can be locked/deleted	✅ Self-custody of projects
❌ Terms of Service dictate rules	✅ You own the rules
❌ Dependent on one company	✅ No single point of failure
❌ Files on centralized servers	✅ Files on decentralized Walrus
❌ Privacy concerns	✅ Complete privacy control

✨ Features

Core Functionality

Decentralized Repositories - Create and manage repos on Sui blockchain
Walrus Storage - Files stored in decentralized Walrus blob storage
Version Control - Commit history and file versioning
Branches - Create and delete branches for parallel development
Pull Requests - Create, merge, and close PRs for collaborative development
Incremental Commits - Smart file change detection and upload only changed files

Privacy & Security

Private by Default - All repositories are private by default
Fine-grained Access Control - Owner, collaborators, and custom access lists
Grant/Revoke Access - Control who can access private repositories
Public Option - Make repositories public when needed

Developer Experience

Interactive CLI Menu - User-friendly menu when running without arguments
Command Aliases - Short aliases for common commands (ls, push, get, branches, prs)
Input Validation - Proper Sui object ID and parameter validation
Colored Output - Clear status messages and progress indicators
Bulk Upload - Upload entire folders with parallel processing
.gitignore Support - Standard .gitignore format for excluding files
Browse Interactively - Browse repos and files with guided navigation
Event-Driven - Real-time updates via Sui events (no indexer needed)

📦 Installation

Prerequisites

Node.js 18+
Sui CLI installed and configured (with an active address in ~/.sui/sui_config/)
Walrus CLI installed

Option 1: Global NPM Installation (Recommended)

Install SuiGit globally from npm:

npm install -g suigit

Then use from anywhere:

suigit create-repo
suigit list
suigit upload

Option 2: Local Development Installation

For development or local testing:

# Clone and install dependencies
npm install

# Build the project
npm run build

# Test locally with npm link
npm link

# Now you can use 'suigit' command from anywhere
suigit create-repo

Configuration

The tool automatically uses your Sui CLI active address from ~/.sui/sui_config/client.yaml. No additional configuration needed!

Optional: Override with environment variables in frontend/.env:

SUI_NETWORK=testnet
PACKAGE_ID=0x81bebbbd57841a44faae752ca6998c0c2b00b6a55501ee60e60896fa1d76e6bb
WALRUS_PUBLISHER=https://publisher.walrus-testnet.sui.io
MAX_FILE_SIZE_MB=10
UPLOAD_RATE_LIMIT_PER_HOUR=50

# Optional: Override Sui CLI wallet (use only if needed)
PRIVATE_KEY=suiprivkey1...

🚀 Quick Start

Interactive Mode (Recommended - Easiest)

suigit
# Presents an interactive menu with all available operations

Command Mode (for Scripting)

# Create a repository
suigit create-repo

# Upload files
suigit upload

# Create a branch
suigit create-branch

# Create and merge a pull request
suigit create-pr
suigit merge-pr

### Using Aliases (Shortcuts)

```bash
suigit ls              # List repositories
suigit push            # Upload files
suigit get             # Download files
suigit branches        # Branch management
suigit prs             # Pull request operations

For Local Development

If using npm link instead of global installation:

npm run cli                    # Interactive menu
npm run cli create-repo        # Create repo
npm run cli ls                 # List repos

📋 Complete Command Guide

🎬 Live Demo / Presentation Commands

Show what it can do:

suigit                      # Shows interactive menu with all options
suigit list                 # Lists all your decentralized repos
suigit show <repo-id>       # Shows repo details, files, commits
suigit browse               # Browse repos and files interactively

📁 Repository Management

Command	Alias	What It Does	GitHub Comparison
`create-repo`	-	Create blockchain repo	Creates on-chain (immutable), private by default, no GitHub needed
`list`	`ls`	List your repos	Shows blockchain repos, not GitHub servers
`browse`	-	Interactive browser	Browse on-chain repos with full details
`show <id>`	-	View repo details	Shows blockchain data: files, commits, branches on-chain

📤 File Operations (Walrus Storage)

Command	Alias	What It Does	Difference from GitHub
`upload`	`push`	Upload files to repo	Files → Walrus (decentralized), blob ID → blockchain
`download`	`get`	Download files	Retrieves from Walrus using blockchain blob IDs

📝 Commits & Tracking

Command	What It Does	Why Different
`commit`	Create manual commit	Recorded on blockchain (immutable)
`commit-incremental`	Smart commit with auto-detect	Only uploads changed files (cost efficient)

🌿 Branch Management

Command	Alias	What It Does	Like Git But...
`create-branch`	`branches`	Create development branches	On blockchain (decentralized)
`delete-branch`	-	Delete a branch	Immutable record of all branches

🔀 Pull Requests

Command	Alias	What It Does	Key Difference
`create-pr`	`prs`	Propose code changes	Recorded on blockchain forever
`merge-pr`	-	Merge approved PR	On-chain transaction, provable proof
`close-pr`	-	Close without merge	Immutable record of decision

🔐 Privacy & Access Control (Unique Feature!)

Command	What It Does	Why Special
`set-public`	Make repo public	Anyone can view/download (no GitHub account needed)
`set-private`	Make repo private	Only you and allowed wallets
`grant-access`	Give wallet permission	Grant Sui wallet addresses (no email invites)
`revoke-access`	Remove wallet permission	Instant revocation (no GitHub management)

🔐 Repository Privacy Model

Default Behavior

All repositories are created as PRIVATE
Only the owner can initially access them
Use set-public to make accessible to everyone

Private Repository Access Control

Owner - Full access to all operations
Collaborators - Can create branches and pull requests (if added)
Granted Access - Custom users added via grant-access
Public - Anyone can read/download (when set-public)

Permission Matrix

Operation	Owner	Collaborators	Public
View/Download	✅	✅	✅
Upload Files	✅	✅ (if private)	✅
Create Branch	✅	✅ (if private)	❌
Create PR	✅	✅ (if private)	❌
Merge PR	✅	❌	❌
Delete Branch	✅	❌	❌
Set Privacy	✅	❌	❌
Grant Access	✅	❌	❌

📁 Using .gitignore

Create a .gitignore file in your project root to exclude files from uploads:

# Dependencies
node_modules/
.venv/

# Build outputs
dist/
build/

# Environment
.env
.env.local

# Logs
*.log
logs/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Negation example - upload despite being a log
!important.log

See .gitignore.example for more patterns.

💡 Example Workflows

Creating Your First Repository

suigit
→ Select "Create a new repository"
→ Enter name: "my-project"
→ Enter description: "My awesome project"
→ Note: Repository ID shown (save this!)

Collaborative Development

# 1. Create repository (private by default)
suigit create-repo

# 2. Create branches
suigit create-branch
→ Branch: main, Commit: initial
suigit create-branch
→ Branch: develop, Commit: initial

# 3. Create PR
suigit create-pr
→ Title: "Add feature X"
→ Source: develop, Target: main

# 4. Merge PR (as owner)
suigit merge-pr
→ PR ID: 0

# 5. Make public (optional)
suigit set-public

Uploading With .gitignore

# Create .gitignore in project
echo "*.log" > .gitignore
echo "node_modules/" >> .gitignore

# Upload - will skip ignored files
suigit upload
→ 25 files found, 3 skipped by .gitignore
→ Uploading 22 files...

🔄 GitHub vs SuiGit - Side by Side

How Workflows Compare

Traditional GitHub:

1. Create account on github.com
2. GitHub controls your account & repos
3. Files stored on GitHub servers
4. GitHub could delete your account anytime
5. You depend on GitHub's infrastructure

SuiGit:

1. Use your existing Sui CLI wallet
2. You control everything (self-custody)
3. Files stored on Walrus (decentralized)
4. Immutable blockchain record
5. No dependency on any company

Key Differences Table

Aspect	GitHub	SuiGit
Control	GitHub owns your repos	You own your repos
Account	Email-based GitHub account	Sui wallet (crypto-native)
Storage	GitHub servers (centralized)	Walrus + Sui (decentralized)
Privacy	Terms of Service controlled	You control everything
Account Lock	Can be suspended/deleted	Immutable blockchain record
Cost Model	Free tier + paid plans	Gas costs on blockchain
Immutability	Can delete repos/history	Permanent blockchain record
Permissions	Email invites	Direct wallet addresses
Collaboration	Through GitHub UI	Through wallet addresses

💼 Use Cases

🎯 For Individual Developers

True Ownership - Your code is yours forever
No Platform Lock-in - Leave anytime without losing history
Privacy First - Private repos are completely private
Self-Sovereignty - No company can delete your account

👥 For Teams

Decentralized Teams - Work without company infrastructure
Transparent History - Immutable record of all changes
Wallet-Based Access - Grant/revoke with wallet addresses
Open Source Friendly - Easy to make public without intermediary

🏢 For Organizations

Self-Hosted Governance - No third-party policy changes
Immutable Audit Trail - Full history on blockchain
Regulatory Compliance - Permanent, auditable records
Data Sovereignty - Control where your data is stored

🌍 For Web3 Projects

Native Blockchain - Integrated with Sui ecosystem
Smart Contracts - Store code alongside contracts
Decentralized DAO - Version control for DAO code
Transparent Governance - Public repo for community projects

⚡ Why Choose SuiGit?

✅ No Intermediary - You control your code ✅ Permanent History - Blockchain immutability ✅ True Decentralization - No company can delete your repos ✅ Wallet Native - Works with your crypto wallet ✅ Cost Efficient - Walrus storage is optimized ✅ Future Proof - Decentralized = future-ready ✅ True Privacy - You decide who sees what ✅ Web3 Ready - Built for blockchain world

🏗️ Architecture

┌─────────────┐
│  CLI User   │
└──────┬──────┘
       │
       ▼
┌──────────────────┐         ┌────────────────────┐
│  Interactive     │◄───────►│  Repository Service│
│  Menu & Commands │         │ (Blockchain Calls) │
└──────────────────┘         └─────────┬──────────┘
                                      │
                ┌─────────────────────┼──────────────────┐
                ▼                     ▼                  ▼
         ┌──────────────┐      ┌──────────────┐  ┌─────────────┐
         │ Sui Blockchain   │      │ Walrus Storage   │  │ Local Files │
         │ (Metadata)       │      │ (File Content)   │  │ (.gitignore) │
         └──────────────┘      └──────────────┘  └─────────────┘

📖 For Developers

Project Structure

SuigitVol2/
├── contracts/sui_git/        # Move smart contracts
│   └── sources/sui_git.move  # Main contract logic
├── frontend/                 # TypeScript CLI
│   ├── src/
│   │   ├── cli.ts           # CLI commands and menu
│   │   ├── repository.ts    # Blockchain interactions
│   │   ├── walrus.ts        # Walrus storage integration
│   │   ├── config.ts        # Configuration manager
│   │   └── gitsuiignore.ts  # .gitignore pattern matching
│   └── dist/                # Compiled JavaScript
└── README.md                # This file

Build and Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run CLI with TypeScript (dev mode)
npm run cli:dev create-repo

# Run compiled CLI (production)
npm run cli create-repo

⚙️ Configuration

Create or edit .env file in frontend/ directory:

# Sui Network
SUI_NETWORK=testnet

# Smart Contract Package ID (from deployment)
PACKAGE_ID=0x...

# Walrus Publisher URL
WALRUS_PUBLISHER=https://publisher.walrus-testnet.sui.io

# Private Key (optional - will use temporary keypair if not provided)
PRIVATE_KEY=suiprivkey1...

# Upload limits
MAX_FILE_SIZE_MB=10
UPLOAD_RATE_LIMIT_PER_HOUR=50

🔗 Smart Contract

The Move smart contract supports:

Repository creation with owner tracking
File upload with Walrus blob ID storage
Commit history tracking
Branch management (create/delete)
Pull request system (create/merge/close)
Privacy control (private/public/access lists)
Event emission for real-time updates

Deployed Package ID: Update in config.ts after deployment

🧪 Testing

Test the interactive menu:

npm run cli
# Choose options from the menu to test all features

Test specific commands:

npm run cli create-repo
npm run cli list
npm run cli show <repo-id>

📝 License

This project is part of the SuiGit decentralized version control system.

🤝 Contributing

Contributions welcome! Areas for enhancement:

Web UI/frontend
Additional storage providers beyond Walrus
Advance diff/merge capabilities
Repository templates
CI/CD integration hooks

╔════════════════════════════════════════════════════════╗
║                                                        ║
║              Thank you for exploring SuiGit!           ║
║                                                        ║
║    Decentralized GitHub on Sui Blockchain             ║
║    🌿 Repositories • 🔐 Privacy • 🚀 Decentralized    ║
║                                                        ║
╚════════════════════════════════════════════════════════╝

Made with ❤️ for decentralized collaboration on Sui

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
contracts/sui_git		contracts/sui_git
frontend		frontend
images		images
test		test
.gitignore		.gitignore
README.md		README.md
TEST_COMMANDS.sh		TEST_COMMANDS.sh
test.txt		test.txt

Folders and files

Latest commit

History

Repository files navigation

🌿 SuiGit - Decentralized GitHub on Sui Blockchain

🎯 The Problem We Solve

✨ Features

Core Functionality

Privacy & Security

Developer Experience

📦 Installation

Prerequisites

Option 1: Global NPM Installation (Recommended)

Option 2: Local Development Installation

Configuration

🚀 Quick Start

Interactive Mode (Recommended - Easiest)

Command Mode (for Scripting)

For Local Development

📋 Complete Command Guide

🎬 Live Demo / Presentation Commands

📁 Repository Management

📤 File Operations (Walrus Storage)

📝 Commits & Tracking

🌿 Branch Management

🔀 Pull Requests

🔐 Privacy & Access Control (Unique Feature!)

🔐 Repository Privacy Model

Default Behavior

Private Repository Access Control

Permission Matrix

📁 Using .gitignore

💡 Example Workflows

Creating Your First Repository

Collaborative Development

Uploading With .gitignore

🔄 GitHub vs SuiGit - Side by Side

How Workflows Compare

Key Differences Table

💼 Use Cases

🎯 For Individual Developers

👥 For Teams

🏢 For Organizations

🌍 For Web3 Projects

⚡ Why Choose SuiGit?

🏗️ Architecture

📖 For Developers

Project Structure

Build and Development

⚙️ Configuration

🔗 Smart Contract

🧪 Testing

📝 License

🤝 Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages