irys-git/README.md

Irys based git-like CLI tool for decentralized repository management

# Irys Git (IGit)

Irys Git is a CLI tool that provides a Git-like workflow on top of Irys (Arweave-based) permanent storage layer.  
Manage your **roadmap, code, and history** in a decentralized, censorship-resistant way with just a Solana wallet.

---

## Features

* **Decentralized Storage**: All commits are stored on the Irys network for permanent preservation and verifiability.
* **Solana Wallet Authentication**: Private keys are encrypted with AES-256-GCM and securely stored in `~/.igit`.
* **Git-Compatible Workflow**: Support for familiar commands like `push / pull / clone / branch / checkout`.
* **Mutable Uploads**: Overwrite (update) capability for the same branch to reduce costs.
* **Permission Management**: Control collaborative work with `add-contributor / remove-contributor / list-contributors`.
* **Security Restrictions**: Upload cost limit (default 1 SOL), dangerous extension blocking, file count & request limits.
* **Rate Limiting**: Per-address request rate limiting to prevent abuse.

---

## Installation

```bash
# Global installation (recommended)
npm install -g irys-git

# Or local installation
npm install irys-git --save-dev
```

> Node.js 18+ is recommended.

---

## Quick Start

```bash
# 1) Login (enter Solana private key, set local password)
igit login

# 2) Initialize existing folder as Irys repository
igit init MyRepo

# 3) Upload changes (based on current branch)
igit push

# 4) Clone from another location
igit clone githirys.xyz/<wallet-address>/<repository-name>

# 5) Sync latest changes
igit pull [repository] [branch]
```

---

## Command Summary

| Command | Description |
| ------- | ----------- |
| `login` | Set up Solana private key and encrypt for storage |
| `init [name]` | Initialize current directory as Irys repository |
| `push [branch]` | Upload current HEAD snapshot to Irys |
| `pull [repo] [branch]` | Download latest snapshot and overwrite |
| `clone <url>` | Clone Irys repository (Git or Irys-metadata mode) |
| `list [repo]` | List my repositories/branches |
| `repo-status` | Check local repository status |
| `checkout [branch]` | Switch branch (create with --create if missing) |
| `switch <branch>` | Git 2.23 style branch switching |
| `branch` | List/create/delete branches, query remote |
| `add-contributor <addr>` | Add contributor (owner only) |
| `remove-contributor <addr>` | Remove contributor (owner only) |
| `list-contributors` | List contributors |
| *Basic Git commands* | Proxy support for most regular Git commands like `git add`, `git log` |

> Use `igit --help` to see all options.

---

## URL Format

* **Wallet address based**: `githirys.xyz/<SolanaAddress>/<Repository>`  
* **Nickname based**: `githirys.xyz/<Nickname>/<Repository>` (nickname → address auto-resolution)  
* **Transaction ID**: `irys://<TransactionId>` or direct input of `<43+ characters>`

---

## Permission Management Workflow

1. **Owner** `init` & `push` repository, fixed with `git-owner` tag.
2. Owner registers contributor addresses with `add-contributor`, storing permission list at **mutable address**.
3. Contributors get automatic edit permission check during `push` and upload to original repository.
4. Can be removed anytime with `remove-contributor`, changes update to same mutable address.

---

## Security ⚠️

* Private keys are encrypted/decrypted only locally and never transmitted over network.
* If upload cost exceeds 1 SOL, console confirmation is required before proceeding.
* The following extensions are blocked from upload: `.exe`, `.bat`, `.cmd`, `.scr`, `.com`, `.pif`, `.jar`
* Default rate limit of 10 calls per minute (varies by command).

---

## Examples

```bash
# Create new branch and switch
igit branch -b feature/login

# Code changes → Git commit
git add .
git commit -m "feat: add login functionality"

# Upload to Irys
igit push feature/login

# Grant contributor permission instead of PR
igit add-contributor 7eYZ...AbC
```

---

## Development & Testing

```bash
git clone https://github.com/yourname/irys-git
cd irys-git
npm install
npm run dev
```

---

## License

MIT