isomorphic-git

isomorphic-git reimplements git’s plumbing and porcelain entirely in JavaScript, so the exact same clone/commit/push/merge code path runs in Node.js and in the browser with no native git binary or C++ addon anywhere in the stack. Instead of assuming a filesystem or HTTP client, every command takes a pluggable fs and http client as an argument, which is what lets the library run against Node’s native fs on the server and against something like LightningFS or ZenFS in the browser without any code changes.

The package covers the same ground as the real git CLI: object read/write (blobs, trees, commits, annotated tags), packfile indexing and delta application, the smart-HTTP wire protocol for fetch/push, merge and cherry-pick, and a typed error hierarchy for programmatic error handling. A thin isogit CLI ships alongside the library, mostly as a way to exercise the JS API from a terminal rather than as a replacement for git itself.

What You Get

• The full set of everyday git porcelain commands (clone, commit, push, pull, fetch, merge, cherry-pick, branch, tag, log) as individually importable, tree-shakeable functions
• Pluggable fs and http client arguments so the same command implementations run against Node’s native filesystem/HTTP or a browser filesystem shim like LightningFS/ZenFS
• Low-level plumbing access (readObject, writeObject, readTree, hashBlob, packObjects, indexPack) for building custom git tooling on top
• A typed error hierarchy (37 subclasses of a shared BaseError with code/data/caller fields) for handling failure cases like merge conflicts or checkout conflicts programmatically
• The isogit CLI for exercising the library’s commands directly against a local repository from a terminal
• TypeScript type declarations generated from JSDoc annotations, giving editor autocomplete without hand-authoring a separate .d.ts surface

Common Use Cases

• In-browser IDEs and playgrounds (e.g. CodeSandbox-style editors) that need real git clone/commit/diff without a server-side git process
• CI/build tooling and codegen scripts that need to script git operations from Node without shelling out to the git binary
• Offline-first or local-first web apps that persist a working tree to browser storage and sync it to a remote over HTTP
• Custom git hosting or git-backed CMS tooling that needs low-level access to packfiles and objects rather than just porcelain commands
• Educational or debugging tools that want to inspect git’s internal object model programmatically

Under The Hood

Architecture Commands are organized in clear layers: a thin api/ surface (e.g. src/api/clone.js) with JSDoc-documented parameters delegates to commands/ for core git logic, which coordinates stateful managers/ (GitConfigManager, GitIndexManager, GitRefManager, GitRemoteHTTP) operating on models/ that mirror git’s own object formats (GitCommit, GitTree, GitPackIndex, GitConfig), backed by a storage/ layer for loose and packed object reads/writes and a wire/ layer that parses and writes the git smart-HTTP protocol. The fs and http clients are injected as arguments rather than assumed globals, which is the core design choice that makes the same command implementations work identically in Node and in the browser. Errors flow through a typed BaseError hierarchy with structured code/data/caller fields rather than ad hoc throws. Because storage and wire both depend directly on the object-model layer, a change to how objects are represented would ripple through nearly every command.

Tech Stack Pure JavaScript with no native dependencies, published as dual ESM/CJS via a conditional exports map, plus a UMD bundle for direct browser <script> use. Its own dependencies are narrowly scoped utilities (pako for zlib inflate/deflate of git objects, crc-32 for packfile checksums, async-lock for concurrency-safe repository operations, ignore for .gitignore matching). Builds run through a custom Rollup pipeline plus Webpack for the UMD bundle, with bundlewatch enforcing a fixed size budget on the minified output. TypeScript declarations are generated from JSDoc rather than hand-authored, and CI runs on both Azure Pipelines and GitHub Actions.

Code Quality Extensive test coverage (around 190 test files) spans Node (Jest) and real browsers (jest-puppeteer) against a shared fixture-repo helper, including dedicated browser-only and server-only test variants and edge-case regression tests for things like symlink handling and bounded delta allocation. @ts-check-annotated JSDoc gives static type checking without a full TypeScript rewrite, ESLint (standard config) plus Prettier enforce consistent style, and a typed error hierarchy replaces generic throws with structured, catchable error classes.

API Design Commands are exported as individually importable, tree-shakeable functions rather than methods on one large class, which keeps browser bundle sizes down since apps only pull in the git operations they call. The injected fs/http client pattern is the defining ergonomic choice that separates it from every wrapper around a native git binary. The bundled isogit CLI doubles as living documentation, printing the equivalent JS call alongside its JSON result for any command it runs. Reimplementing an entire version-control protocol — object model, packfiles, and wire format — in dependency-free JavaScript that runs unmodified in a browser tab is a genuinely uncommon technical undertaking among JS packages.