git-wasm-calepin

libgit2 compiled to WebAssembly with the OPFS (Origin Private File System) backend — a production module for browser-resident git repositories with persistent local storage.

Forked from petersalomonsen/wasm-git. The upstream POC carried three runtime variants (sync / async / OPFS); this fork keeps only OPFS and restructures the project as a standalone deliverable. See ADR-0001 and ADR-0003 for the rationale.

Status

Pre-1.0. Distributed through Forgejo Releases as tarballs (no npm publish — see ADR-0002). API may evolve until v1.0.0. Support policy: docs/03-development/support.md.

Use cases

• Browser-resident git clients that need a persistent local working copy (notebook apps, offline-first editors, in-browser CI front-ends).
• Static-site authoring tools that round-trip commits without a server.
• Reproducible build harnesses that need git semantics inside a sandboxed Web Worker.

If your workload is one-shot (clone, read, discard) and does not require persistence, the upstream sync or async variants of wasm-git may be a better fit. This project is OPFS-only by design.

Compatibility

Component	Pinned version
libgit2 (vendored)	1.9.3
Emscripten	4.0.23
Node.js (dev only)	22.20.0 LTS (Jod)

Browsers must support WebAssembly, SharedArrayBuffer, Atomics, and OPFS via the File System Access API:

• Chrome / Edge 86+
• Firefox 111+
• Safari 15.2+

Install

Download the latest release tarball from Forgejo Releases, verify the attached SHA256SUMS, and serve lg2_opfs.js + lg2_opfs.wasm alongside your worker script:

curl -LO https://git.jombi.fr/duhamed/git-wasm-calepin/releases/download/v0.1.0/git-wasm-calepin-0.1.0.tar.gz
curl -LO https://git.jombi.fr/duhamed/git-wasm-calepin/releases/download/v0.1.0/SHA256SUMS
sha256sum -c SHA256SUMS
tar xzf git-wasm-calepin-0.1.0.tar.gz

A signed checksum manifest (minisign) is attached to each release. See docs/03-development/build.md for the verification procedure.

Minimal example

The OPFS build runs inside a Web Worker. The hosting page must serve the following headers to enable SharedArrayBuffer:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Inside the worker:

const lgMod = await import('./lg2_opfs.js');
const lg = await lgMod.default();
const FS = lg.FS;

// WASMFS does not pre-create /home/web_user like MEMFS did.
try { FS.mkdir('/home'); } catch (_) {}
try { FS.mkdir('/home/web_user'); } catch (_) {}
FS.writeFile('/home/web_user/.gitconfig',
  '[user]\n  name = Your Name\n  email = you@example.com');

// Mount OPFS under /opfs.
const backend = lg._lg2_create_opfs_backend();
const workingDir = '/opfs';
lg.ccall('lg2_create_directory', 'number', ['string', 'number', 'number'],
         [workingDir, 0o777, backend]);

const repoDir = `${workingDir}/myrepo`;
lg.callMain(['clone', 'https://example.com/repo.git', repoDir]);

// WASMFS getcwd() workaround — see docs/01-architecture/patches/ for context.
FS.symlink(repoDir, '/myrepo');
FS.chdir(repoDir);

FS.writeFile('newfile.txt', 'Hello OPFS!');
lg.callMain(['add', 'newfile.txt']);
lg.callMain(['commit', '-m', 'Add new file']);
lg.callMain(['push']);

A complete end-to-end example lives under examples/opfs/. The API reference is in docs/03-development/api.md.

Building from source

git clone https://git.jombi.fr/duhamed/git-wasm-calepin.git
cd git-wasm-calepin
make setup                  # downloads libgit2 1.9.3 + emsdk 4.0.23 + npm deps
make build                  # builds the OPFS artifact (Release)
make test                   # Node test suite
make test-browser           # browser test suite (Playwright + Web Test Runner)

For a reproducible toolchain, use the bundled Docker image:

make dev                    # interactive shell in git-wasm-calepin/dev:local

Detailed build instructions, troubleshooting, and reproducibility notes are in docs/03-development/build.md.

Documentation

• docs/03-development/build.md — build prerequisites, troubleshooting, reproducibility checks
• docs/03-development/api.md — OPFS API reference and usage snippets
• docs/01-architecture/patches/ — one sheet per C patch applied to libgit2
• docs/01-architecture/adr/ — Architecture Decision Records
• docs/03-development/support.md — support policy and version matrix
• docs/02-planning/analyses/ — historical analysis journal (French)
• CONTRIBUTING.md — development workflow, hooks, commit conventions
• SECURITY.md — vulnerability disclosure and supply-chain notes
• CHANGELOG.md — release notes

License & commercial use

SPDX expression: GPL-2.0-only WITH LicenseRef-libgit2-linking-exception (see COPYING for the canonical text and LICENSES/ for the SPDX-style layout).

The linking exception (modeled on the GNU Classpath exception) means the compiled artifact lg2_opfs.wasm can be linked into and redistributed with proprietary software, including for commercial purposes, without GPL contagion. The source form of this repository, including the C patches under patches/, remains under GPL-2.0-only.

When redistributing the compiled artifact, you must:

1. Include COPYING (or a pointer to it).
2. Note the vendored libgit2 version (currently 1.9.3).
3. Make the patched libgit2 sources available — linking back to this Forgejo repository satisfies that obligation.

Full legal analysis: section 3 of docs/02-planning/analyses/2026-05-15-restructuration-production.html. Decision record: ADR-0004.

Acknowledgements

See AUTHORS.md. The upstream petersalomonsen/wasm-git POC and the libgit2 project are credited there and in NOTICE.