Embeddable version control system

Note

Lix is in alpha · Follow progress to v1.0 →

---

Lix is an embeddable version control system for files of any format (DOCX, XLSX, CAD, PDF, JSON) with semantic, per-entity diffs. Branches, merge, and an immutable change history, exposed as SQL, all in-process.

Use it inside a contract editor, a feature-flag service, an artifact registry, an AI-agent platform, a versioned filesystem, or a domain-specific CLI.

Lix is to version control what DuckDB is to analytics: an embeddable engine with pluggable support for file formats.

• It's just a library. npm install, import, run. No daemon, no protocol, no remote.
• Semantic per-entity diffs. XLSX cells, DOCX clauses, CAD parts. Not line-by-line text.
• History is SQL. Diffs, blame, and audit are direct queries against lix_change.

The entity foundation ships today. A plugin API is on the roadmap; once it lands, anyone can author a plugin that turns a file format (DOCX, XLSX, CAD, PDF, anything else) into entities.

How does Lix compare to Git? →

Getting started

JavaScript · Python · Rust · Go

npm install @lix-js/sdk

import { openLix } from "@lix-js/sdk";

const lix = await openLix(); // in-memory by default; pass a backend for persistence

// Register a schema for a tracked entity
await lix.execute(
  "INSERT INTO lix_registered_schema (value) VALUES (lix_json($1))",
  [
    JSON.stringify({
      "x-lix-key": "task",
      "x-lix-version": "1",
      "x-lix-primary-key": ["/id"],
      type: "object",
      required: ["id", "title"],
      properties: {
        id: { type: "string" },
        title: { type: "string" },
      },
      additionalProperties: false,
    }),
  ],
);

// Write rows like any SQL table
await lix.execute(
  "INSERT INTO task (id, title) VALUES ($1, $2)",
  ["t1", "Ship v1"],
);

// Every change is journaled; query it with SQL
const changes = await lix.execute(
  "SELECT entity_id, schema_key, snapshot_content FROM lix_change",
);

Semantic change (delta) tracking

Unlike Git's line-based diffs, Lix understands file structure through plugins. Lix sees price: 10 → 12 or cell B4: pending → shipped, not "line 4 changed" or "binary files differ".

JSON file example

Before:

{"theme":"light","notifications":true,"language":"en"}

After:

{"theme":"dark","notifications":true,"language":"en"}

Git sees:

-{"theme":"light","notifications":true,"language":"en"}
+{"theme":"dark","notifications":true,"language":"en"}

Lix sees:

property theme:
- light
+ dark

Excel file example

The same approach works for binary formats. With an XLSX plugin, Lix shows cell-level changes:

Before:

  | order_id | product  | status   |
  | -------- | -------- | -------- |
  | 1001     | Widget A | shipped  |
  | 1002     | Widget B | pending |

After:

  | order_id | product  | status   |
  | -------- | -------- | -------- |
  | 1001     | Widget A | shipped  |
  | 1002     | Widget B | shipped |

Git sees:

-Binary files differ

Lix sees:

order_id 1002 status:

- pending
+ shipped

How Lix Works

Lix uses SQL databases as query engine and persistence layer. Virtual tables like file and file_history are exposed on top:

SELECT * FROM file_history
WHERE path = '/orders.xlsx'
ORDER BY created_at DESC;

When a file is written, a plugin parses it and detects entity-level changes. These changes (deltas) are stored in the database, enabling branching, merging, and audit trails.

┌─────────────────────────────────────────────────┐
│                      Lix                        │
│                                                 │
│ ┌────────────┐ ┌──────────┐ ┌─────────┐ ┌─────┐ │
│ │ Filesystem │ │ Branches │ │ History │ │ ... │ │
│ └────────────┘ └──────────┘ └─────────┘ └─────┘ │
└────────────────────────┬────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│                  SQL database                   │
│            (SQLite, Postgres, etc.)             │
└─────────────────────────────────────────────────┘

Read more about Lix architecture →

Roadmap

• Core API (<v0.5)
• ACID transactions (v0.6)
• Branching, diffing, merging (v0.6)
• SQL API (v0.6)
• Stable physical storage layout (v0.6)
• Plugin API for file formats (community-authored plugins for DOCX, XLSX, CAD, PDF, …)
• Merge conflict semantics and resolution
• Working changes & checkpointing
• Real-time sync

Learn More

• Getting Started Guide - Build your first app with Lix
• Documentation - Full API reference and guides
• Discord - Get help and join the community
• GitHub - Report issues and contribute

Blog posts

• Introducing Lix: An embeddable version control system
• What if a Git SDK to build apps exists?
• Git is unsuited for applications
• Does a git-based architecture make sense?

License

MIT