isomorphic-git: a pure JavaScript git that runs in Node and the browser

Interoperability as the stated goal

The definition in the README is a pure JavaScript reimplementation of git that works in both Node.js and browser JavaScript environments, and it can read and write to git repositories and fetch from and push to git remotes such as GitHub, all without any native C++ module dependencies.

The goal statement is what makes this interesting rather than merely unusual. Isomorphic-git aims for 100 percent interoperability with the canonical git implementation, and the mechanism is spelled out: it does all its operations by modifying files in a `.git` directory just like the git you are used to. There is no alternative object store, no private metadata format, no sidecar database. A repository it writes is a repository the real git can open, which means you can hand the result to a server, a CI job, or a colleague's desktop without a conversion step.

Two supporting design choices come out of that goal. The API is designed with bundlers like Rollup and Webpack in mind, and functionality is exposed as individual functions so a bundler can drop the ones your application never calls. The project also ships type definitions, so editors such as VS Code and CodeSandbox get static checking and completion. Both of those are quality of life features that matter more in a library you embed in an application than in a command line tool.

The package manifest backs this up. `sideEffects` is false, the `exports` map carries separate type and entry points for Node and for the default browser build, and there are subpath exports for `http/node`, `http/web`, `managers` and `models`. A `bin` entry named `isogit` points at `cli.cjs`.

You supply the file system and the HTTP client

The interesting engineering problem in running the same code in a server and a browser is not the git algorithms. Git reads the file system and speaks HTTP, and a browser has neither `fs` nor a Node HTTP client. Rather than reaching for polyfills or conditional imports, isomorphic-git inverts the dependency and asks the caller to provide both.

In Node you hand it the native `fs` module and a provided client.

// node.js example
const path = require('path')
const git = require('isomorphic-git')
const http = require('isomorphic-git/http/node')
const fs = require('fs')

const dir = path.join(process.cwd(), 'test-clone')
git.clone({ fs, http, dir, url: 'https://github.com/isomorphic-git/lightning-fs' }).then(console.log)

In the browser you need something that emulates the `fs` API, and the README recommends LightningFS, written and maintained by the same author and described as part of the isomorphic-git suite. ZenFS and Filer are named as alternatives. The HTTP client changes too, from `isomorphic-git/http/node` to `isomorphic-git/http/web`.

<script src="https://unpkg.com/@isomorphic-git/lightning-fs"></script>
<script src="https://unpkg.com/isomorphic-git"></script>
<script type="module">
import http from 'https://unpkg.com/isomorphic-git@beta/http/web/index.js'
const fs = new LightningFS('fs')

const dir = '/test-clone'
git.clone({ fs, http, dir, url: 'https://github.com/isomorphic-git/lightning-fs', corsProxy: 'https://cors.isomorphic-git.org' }).then(console.log)
</script>

That `corsProxy` argument is the part that surprises people. Browsers will not let a page read cross origin responses from GitHub without permission, so the browser example routes through a proxy the project hosts at `cors.isomorphic-git.org`. If you deploy this, that is a third party in the data path and a decision you have to make deliberately.

The README also flags a durability hazard honestly. LightningFS may apply file operations out of order, which can lead to repository corruption if the process crashes, and the suggested mitigation is calling `fs.flush()` after git operations. A library that warns you about its recommended storage backend is doing you a favor.

Community maintained, and the README says so plainly

The project status section is the most unusual part of the README and it is worth reading before anything else. The original author, Billie Hilton, left the project, and it is now maintained by two volunteers, listed as jcubic, described as most active, and mojavelinux. The README then says they do not write much code, mainly do code review and try to answer issues and on Gitter, and that they do not want the project to die.

The consequence is stated without softening: the project is community driven, which means that if you want a feature implemented you need to do it yourself or find someone willing to write the code. There is some money on OpenCollective that can be spent on development, and the README says not to expect a full salary from it.

So the practical reading is that isomorphic-git is stable rather than actively extended. It gets bug fixes, and it gets them promptly enough: v1.42.2 was published on 2026-09-11 with two fixes in it, sanitizing remote refs and correcting a wrong ref, seven hours after v1.42.1. The repository was last pushed the same day. The repository has 8,355 stars, 492 forks and 307 open issues.

That last number deserves attention next to the maintenance model. A quarter of the star count in open issues against two reviewers is what a community project looks like from the outside. The README also keeps a release notes link and a blog post for anyone upgrading from the 0.x line to 1.x, which is the kind of pointer that matters when the API has been stable across a major version.

The support table and the engines field disagree

The README includes a table of supported environments with a set of version numbers in it: Node 10, Chrome 79, Edge 79, Firefox 72, Safari 13, Android 10 and iOS 13. Those are the numbers the README says are tested in CI and will continue to be supported until the next breaking version.

The package manifest says something different. Its `engines` field requires Node 14.17 or newer.

Both statements are in the repository right now and they do not agree. The most likely explanation is that the README table is stale text carried forward from the 0.x era, while the manifest tracks the real build target, but the README is the document most people read first. If you are deciding whether a Node version is safe, the manifest is the more reliable of the two, and the browser numbers deserve the same suspicion.

The rest of the toolchain in the tree is modern and consistent with the bundler focused goals. Build orchestration runs through nps with `package-scripts.cjs`, there is a rollup config and a webpack config, jest configuration for Node and a separate `jest-browser.config.js` with a puppeteer config beside it, and an azure pipelines file for CI. Renovation handles dependency updates, and the `website/` directory at the root is the documentation site that lives in the same repository.

Testing in a real browser is worth noting for a library whose entire premise is that it runs in two environments. A jest browser config and puppeteer settings indicate that the browser half is exercised, not assumed.

What the repository layout reveals about the design

The tree separates concerns in a way that mirrors the architecture. `src/` holds the implementation, `__tests__/` the test suite, and `docs/` and `website/` the documentation. There is a `.extra/` directory and a `.config/` directory that are easy to miss and suggest per environment build outputs, and `cli.cjs` sits at the root as the `isogit` command the README mentions as able to operate on repositories on your desktop or server.

The subpath exports named `managers` and `models` are the interesting pair. Exporting those suggests the internal split between classes that manage state and objects that describe data, which is a sensible way to organize a git implementation where things like a commit, a tree, and a blob are all structured records with validation. It also means those internals are part of the published surface, which helps when you need to work at a level below the high level commands.

The import styles the README demonstrates reflect the same thinking. A default import for convenience, a namespace import, or named imports for tree shaking:

import git from 'isomorphic-git'
// or
import * as git from 'isomorphic-git'
// or
import {add, clone, commit, push} from 'isomorphic-git'

A UMD build is declared for jsdelivr and unpkg, which is how the script tags in the browser example can load the library without a bundler at all.

Where it fits against the real git

The honest comparison is not isomorphic-git against other JavaScript libraries. It is isomorphic-git against shelling out to the git binary, which is what most server side tools do.

Against the binary, isomorphic-git wins in environments where the binary is a problem: a browser tab, an edge worker, a bundled desktop application, a sandbox where compiling or shipping git is unwelcome. It also wins when you want the same code path on client and server, because the filesystem and HTTP client are parameters rather than environment branches.

The binary wins on everything else, and not narrowly. Canonical git has a decade of performance work behind its packfile handling, it supports every extension ever invented, and it has a version control system's worth of behaviour that a pure JavaScript reimplementation will always trail on. The README's interoperability goal is about file format compatibility, and it does not claim performance parity or feature parity.

The most common sensible use is read and inspect rather than write. Reading history, resolving a commit, listing files at a revision, and checking out into an emulated filesystem are all well within what this library does well. Push and merge conflict resolution are the features where you would want to be most careful, and where the rate of open issues deserves a look before you commit to that path.

The repository topics say `browser`, `git`, `isomorphic-javascript`, `javascript`, `nodejs` and `vcs`, which is an accurate summary of the territory. The license is MIT.

Editorial conclusion

isomorphic-git earns its place in a specific set of situations: a browser application that needs to read or write a real repository, a build step that has to touch git history without a binary, and any environment where a native module will not install. What it offers is genuine interoperability rather than approximation, since it modifies the same `.git` directory the canonical implementation does. The costs are equally concrete. The project is community maintained by two volunteers who mostly review, feature work is slow, and there are 307 open issues against 8,355 stars. Start from the Node example with the built in client, because the browser path additionally depends on an emulated file system whose durability you have to manage yourself.

Frequently asked questions

Official sources

1. isomorphic-git/isomorphic-git on GitHub
2. License: MIT
3. Project website
4. README
5. Releases