Git Mesh

Git Mesh is a peer-to-peer, decentralized Git remote system. It allows developers to synchronize Git repositories directly between machines without relying on a central server like GitHub or GitLab.

Utilizing libp2p for decentralized networking and tokio for high-performance asynchronous IPC, Git Mesh provides a seamless "serverless" experience for collaborative Git workflows.

Table of Contents

• Architecture
• Crates
• Quick Start
• Usage
• How it Works
• Development
• License

Architecture

Git Mesh is built with a distributed approach:

• Local Daemon (gitmesh-daemon): Runs in the background, managing P2P connections, repository synchronization, and and the local IPC server.
• CLI & Remote Helper (gitmesh-cli): Provides the git-remote-gitmesh binary which Git uses to communicate with the daemon.
• Lighthouse (gitmesh-lighthouse): A lightweight signaling/relay node that facilitates NAT traversal and initial peer discovery for nodes over the internet.

graph TD
    subgraph "Local Machine"
        Git["Git CLI"]
        CLI["gitmesh-cli (Remote Helper)"]
        Daemon["gitmesh-daemon"]
    end
    
    subgraph "P2P Network"
        PeerA["Peer A (Daemon)"]
        PeerB["Peer B (Daemon)"]
        Lighthouse["Lighthouse (Lighthouse / Relay)"]
    end
    
    Git <-->|Stdin/Stdout| CLI
    CLI <-->|Named Pipe / Unix Socket| Daemon
    Daemon <-->|mDNS / Relay| Lighthouse
    Daemon <-->|TCP / Gossipsub| PeerA
    Daemon <-->|TCP / RequestResponse| PeerB

Crates

• gitmesh-core: Shared data types, protocol definitions, and serialization logic.
• gitmesh-daemon: The main service managing the libp2p swarm and repository sync.
• gitmesh-cli: The user-facing command line and the git-remote-gitmesh executable.
• gitmesh-lighthouse: The public-facing bootstrap and relay node.

Quick Start

1. Build the project

Requires Rust 1.75+.

cargo build --release

2. Set up the Remote Helper

For Git to find the helper, ensure the binary is in your PATH and named git-remote-gitmesh. On Windows:

cp target/release/gitmesh-cli.exe target/release/git-remote-gitmesh.exe
$env:PATH += ";$(Get-Location)\target\release"

3. Start the Daemon

cargo run --release -p gitmesh-daemon

4. (Optional) Run a Lighthouse

cargo run --release -p gitmesh-lighthouse

Usage

Once the daemon is running and the remote helper is in your PATH, you can use Git Mesh remotes:

Add a mesh remote

git remote add mesh gitmesh://my-secret-repo

List refs

git ls-remote mesh

Synchronize (Push/Pull)

Note: Full sync logic is currently under development.

git push mesh main
git pull mesh main

How it Works

1. IPC (Inter-Process Communication)

The CLI communicates with the Daemon using platform-optimized IPC:

• Windows: Named Pipes (\\.\pipe\gitmesh-daemon)
• Unix: Unix Domain Sockets (/tmp/gitmesh.sock)

2. P2P Discovery

Nodes discover each other using a multi-layered approach:

• Local Network: mDNS automatically finds other Git Mesh instances on the SAME LAN.
• Internet: Nodes connect to a "Lighthouse" (via a static multiaddr) which acts as a bootstrap peer and a Circuit Relay v2 for NAT traversal.

3. Sync Protocol

Synchronization uses libp2p-request-response over CBOR to negotiate Git refs and transfer packfiles efficiently. Gossipsub is used to announce new commits across the mesh in real-time.

Development

Prerequisites

• Rust (latest stable)
• Git

Testing

cargo test --workspace

License

MIT