Suture

A version control system that understands your file formats.

Unlike Git, which treats every file as opaque bytes, Suture uses semantic drivers to perform intelligent merges on JSON, YAML, CSV, XML, TOML, Markdown, DOCX, XLSX, and PPTX files.

  Git merge on JSON:                    Suture merge on JSON:
  ┌─────────────────────┐              ┌─────────────────────┐
  │ <<<<<<< HEAD        │              │ {                   │
  │   "host": "prod",   │              │   "host": "prod",   │  ← from theirs
  │   "port": 8080      │              │   "port": 3000,     │  ← from ours  
  │ =======             │              │   "debug": true     │  ← from theirs
  │   "host": "staging" │              │ }                   │
  │   "port": 8080      │              └─────────────────────┘
  │ >>>>>>> staging     │              No conflict. Both changes applied.
  │   "debug": true     │
  └─────────────────────┘
  Conflict markers in your file.

Who is this for?

• DevOps teams collaborating on Kubernetes YAML, Docker Compose, CI/CD configs
• Data teams editing JSON/YAML/CSV pipelines and schemas
• Documentation teams working with DOCX, XLSX, PPTX where Git's line merge is catastrophic
• Config-as-code teams managing TOML, XML, properties files across environments

Why Suture?

• No more false merge conflicts on JSON. Two people edit different keys in a config file — Git produces a conflict. Suture merges them cleanly at the field level.
• Structural YAML/TOML merge. DevOps teams working on Kubernetes manifests or Cargo.toml files can edit different sections in parallel without conflicts.
• Office document merge. DOCX, XLSX, and PPTX files are parsed via OpenXML so changes to different paragraphs, cells, or slides merge automatically.
• Patch-based history. Changes are modeled as patches in a DAG, not whole-file snapshots. Conflicts are detected by logical address overlap, not line overlap.

Install

cargo install suture-cli

Requires Rust 1.85+. See rustup.rs to install Rust.

Binary releases (Linux x86_64/aarch64, macOS x86_64/aarch64):

# Downloads and installs to ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/WyattAu/suture/main/install.sh | sh

Or grab the tarball from GitHub Releases directly.

Hub (Web UI)

Run suture-hub to start a web-based patch browser on port 50051:

suture-hub --db suture.db
# Open http://localhost:50051

The hub provides repository browsing, user management, and replication status.

Quick Start

# Install
cargo install suture-cli

# Init a repo and set your identity
suture init
suture config user.name "Your Name"

# Create a JSON config file and commit it
echo '{"host": "localhost", "port": 3000}' > config.json
suture add .
suture commit "base config"

# Create a branch and change one key
suture branch staging
suture checkout staging
echo '{"host": "staging.example.com", "port": 3000}' > config.json
suture add .
suture commit "point to staging"

# Switch back and change a different key
suture checkout main
echo '{"host": "localhost", "port": 8080}' > config.json
suture add .
suture commit "change port"

# Merge — both changes are combined, zero conflicts
suture merge staging
cat config.json
# {"host": "staging.example.com", "port": 8080}

That's the demo. Suture understood the JSON structure and merged both sides — host from staging, port from main — without conflict markers. Git would have produced a merge conflict on every line.

The same semantic merge works for YAML, TOML, CSV, XML, Markdown, DOCX, XLSX, and PPTX files.

Semantic Drivers

Files without a matching driver fall back to line-based diff and merge, same as Git.

Git Merge Driver

Suture can be used as a Git merge driver to get semantic merging inside existing Git workflows — no need to switch VCS. Configured file types (JSON, YAML, TOML, etc.) are merged at the field level instead of line-by-line.

CLI Reference

Run suture --help for the full list.

Architecture

Suture stores content as BLAKE3-hashed blobs (with Zstd compression) and models changes as patches in a directed acyclic graph, persisted to SQLite in WAL mode. Each patch records the logical addresses it modifies; two patches conflict only when those address sets overlap.

The codebase is split into focused crates — core engine, CLI, semantic drivers (one per format), Hub server, TUI, LSP, and more. See docs/ for detailed design documentation.

Comparison

See docs/comparison.md for a detailed feature comparison.

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and pull request workflow.

License

Apache License, Version 2.0. See LICENSE for details.