Lgh

LGH - LocalGitHub

中文文档

LGH (LocalGitHub) is a lightweight local Git hosting service. It wraps git http-backend to provide GitHub-like HTTP access, running entirely on localhost - turning your local directory into a Git server.

✨ Features

• 🚀 Lightweight - Single binary, no external dependencies
• 🔧 Easy to Use - Intuitive CLI commands, one-click repository setup
• 🌐 HTTP Access - Standard Git HTTP protocol, compatible with all Git clients
• 🔒 Authentication - Built-in Basic Auth with salted password hashing
• 🛡️ Read-Only Mode - Optional read-only mode to protect repositories
• 📡 mDNS Discovery - Automatic LAN discovery for team collaboration
• 🌍 Tunnel Support - One-click expose to internet (ngrok, cloudflared)
• ⚡ Smart Archival (v1.2.0) - lgh up / lgh save commands with auto .gitignore
• 🤖 MCP Server (v1.2.0) - AI Agent integration (Cursor, Claude Desktop)

📦 Installation

Option 1: Download Pre-built Binary (Recommended)

Download the pre-built binary for your system — these links always point to the latest release:

# Install after download (macOS ARM64 example)
chmod +x lgh-darwin-arm64
sudo mv lgh-darwin-arm64 /usr/local/bin/lgh

Windows Installation

1. Download lgh-windows-amd64.exe
2. Rename to lgh.exe
3. Move to a folder in your %PATH% (e.g., C:\Program Files\lgh\)
4. Run in PowerShell or Command Prompt

Option 2: Install Script

# Install
curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/install.sh | bash

# Uninstall
curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/uninstall.sh | bash

Option 3: Homebrew (macOS)

# Add tap
brew tap JoeGlenn1213/tap

# Install
brew install lgh

# Uninstall
brew uninstall lgh

Option 4: Build from Source

git clone https://github.com/JoeGlenn1213/lgh.git
cd lgh
make build
sudo make install

# Or manually
go build -o lgh ./cmd/lgh/
sudo mv lgh /usr/local/bin/

Option 5: Go Install

go install github.com/JoeGlenn1213/lgh/cmd/lgh@latest

🚀 Quick Start

1. Initialize LGH Environment

lgh init

This creates the necessary directories and config files in ~/.localgithub/.

2. Start the Server

# Start in foreground
lgh serve

# Start in background (daemon mode)
lgh serve -d

# Check server status
lgh status

# Stop the server
lgh stop

Server listens on http://127.0.0.1:9418 by default.

3. One-Step Add & Push (v1.0.9+)

The fastest way to host a local project:

cd your-project
lgh add . --push

This single command will:

1. Initialize a Git repo (if not already one).
2. Auto-Commit all files (if the repo is empty).
3. Register it with LGH.
4. Auto-Push to the server immediately.

4. Add Without Pushing

If you prefer manual control:

lgh add .
# Then push manually later
git push -u lgh main

5. Smart Archival (v1.2.0+)

The fastest way to backup and sync your code:

# One-click: auto .gitignore + add + commit + push
lgh up "commit message"

# Local save only (no push)
lgh save "WIP: work in progress"

Smart Ignore automatically:

• Detects project type (Python, Go, Node, Java, Rust, AI/ML)
• Generates appropriate .gitignore file
• Blocks large files (>50MB) and sensitive files (.env, *.key)
• (v1.2.3+) When used via MCP, returns exact triggered_job_ids: [...] array, allowing AI to track pipeline status with zero blind spots

5. Push Code

After adding, you can use standard Git commands:

git push lgh main
# or
git push

5. Clone from Elsewhere

git clone http://127.0.0.1:9418/your-project.git

📖 Command Reference

Repository Management (v1.0.4+)

LGH provides tools to manage your local repository state without complex git commands.

Check Connection State

See exactly which remote you are pushing to:

lgh repo status

Switch Remote

Easily switch between LGH and origin (e.g., GitHub):

lgh remote use lgh      # Switch upstream to LGH
lgh remote use origin   # Switch upstream to Origin

Other Tools

# Clone easily (no full URL needed)
lgh clone my-project

# Inspect bare repo details (HEAD, branches)
lgh repo inspect my-project

# Set default branch for bare repo
lgh repo set-default my-project main

# Check system health
lgh doctor

Monitoring & Logs (v1.0.5+)

Track system activity and repository changes in real-time.

# View recent events
lgh events

# Watch for new events (like 'tail -f')
lgh events --watch

```bash
# Filter by type
lgh events --type git.push

Agent Integration (v1.1.0+)

LGH is designed to be the "source of truth" for AI Agents.

1. Real-time Subscription (Socket) Connect to the Unix Domain Socket at ~/.localgithub/lgh.sock to receive a real-time stream of JSON events for every action (repo added, git push, etc.).

• Protocol: Unix Socket, JSON Lines.
• Security: Read-Only. Only the local user can connect.

2. Event Replay (Simulation) Inject past events back into the system to test your Agents without performing real Git actions.

# Replay last 10 events to all connected agents
lgh events replay --last 10

# Replay specific event types
lgh events replay --type git.push

Note: Replayed events include “_replayed”: true in their payload.

Server Options

# Daemon mode (background)
lgh serve -d

# Read-only mode (disable push)
lgh serve --read-only

# Custom port
lgh serve --port 8080

# Enable mDNS for LAN discovery
lgh serve --mdns

# Bind to all interfaces (LAN access)
lgh serve --bind 0.0.0.0

🤖 MCP Quick Setup Guide

Want to connect LGH to Cursor or Claude Desktop?

Scenario 1: You already have LGH installed

Simply update your AI editor's config file (e.g., ~/.cursor/mcp.json) with:

{
  "mcpServers": {
    "lgh": {
      "command": "lgh",
      "args": ["mcp"]
    }
  }
}

Scenario 2: You don't have LGH yet (One-Click Install)

Run this single command to install the latest binary:

curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/install.sh | bash

Once installed, follow the "Scenario 1" step. We designed LGH as a single binary, so you don't need a separate "MCP Plugin". The lgh binary IS the MCP server!

Verify Setup

Ask your AI Agent:

"Check LGH status"

If it calls lgh_status and responds, you're all set!

Add Repository Options

# Custom name
lgh add . --name custom-name

# Don't auto-add remote
lgh add . --no-remote

🔐 Authentication

Enable authentication when sharing repositories over the network:

Setup Authentication

# Interactive setup (hidden password input)
lgh auth setup

# View auth status
lgh auth status

# Generate password hash (for manual config)
lgh auth hash

# Disable auth
lgh auth disable

Client Authentication

# Method 1: URL embedded credentials
git clone http://username:password@192.168.1.100:9418/repo.git

# Method 2: Use Git credential helper
git config credential.helper store
git clone http://192.168.1.100:9418/repo.git
# Enter username/password on first access

Security Best Practices

⚠️ Security Note: Password must be at least 8 characters. Config file stores salted hash, not plaintext.

See docs/SECURITY.md for detailed security guidelines.

🏗️ Directory Structure

~/.localgithub/
├── config.yaml          # Global config
├── mappings.yaml        # Repository mappings
├── lgh.pid             # Server PID file
└── repos/              # Bare repository storage
    ├── MyApp.git/
    └── ProjectB.git/

⚙️ Configuration

~/.localgithub/config.yaml:

port: 9418
bind_address: "127.0.0.1"
repos_dir: "/Users/you/.localgithub/repos"
read_only: false
mdns_enabled: false

# Authentication (optional)
auth_enabled: true
auth_user: "git-user"
auth_password_hash: "salt:hash..."

🌐 Tunnel Feature

LGH supports multiple ways to expose your local service to the internet:

# Show all available tunnel methods
lgh tunnel

# Use ngrok
lgh tunnel --method ngrok

# Use Cloudflare Tunnel
lgh tunnel --method cloudflared

# SSH reverse proxy
lgh tunnel --method ssh

⚠️ Security Note: Always enable authentication (lgh auth setup) or use a reverse proxy before exposing to the internet.

🔧 Advanced Usage

LAN Sharing (with Auth)

# 1. Setup auth
lgh auth setup

# 2. Bind to all interfaces with read-only mode
lgh serve --bind 0.0.0.0 --read-only --mdns

# 3. Access from other devices (requires auth)
git clone http://username:password@your-hostname.local:9418/repo.git

Production Deployment (Recommended)

# 1. LGH listens on localhost only
lgh serve

# 2. Use Caddy reverse proxy + auto HTTPS
# Caddyfile:
# git.example.com {
#     basicauth * {
#         user $2a$14$...
#     }
#     reverse_proxy localhost:9418
# }

CI/CD Integration

# Temporarily expose for GitHub Actions
lgh auth setup
lgh tunnel --method ngrok &
# Use ngrok URL + credentials

⚖️ Comparison with Other Solutions

LGH's Position: Fills the gap between "simple file sharing" and "full Git platform".

🧪 Testing

# Run all tests
go test ./... -v

# Run integration tests
go test ./test/... -v

# Skip long-running tests
go test ./... -v -short

📋 System Requirements

• Go 1.23+ (for building)
• Git (runtime)
• macOS, Linux, or Windows

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Create Pull Request

📄 License

This project is licensed under the MIT License - see LICENSE file.

🙏 Acknowledgments

• spf13/cobra - CLI framework
• spf13/viper - Configuration management
• fatih/color - Terminal coloring
• hashicorp/mdns - mDNS support

---

<p align="center"> Made with ❤️ by <a href="https://github.com/JoeGlenn1213">JoeGlenn1213</a>; </p>