isomorphic-git is a comprehensive, pure JavaScript re-implementation of the Git protocol and repository management, designed to operate seamlessly in both Node.js environments and web browsers. It enables applications to read from, write to, fetch from, and push to Git repositories without requiring any native C++ modules or the system's `git` executable. The current stable version is 1.37.5, with frequent patch releases addressing bug fixes and occasional minor features. The project aims for 100% interoperability with the canonical Git implementation, operating on standard `.git` directories. A key differentiator is its modular API, which allows bundlers like Rollup and Webpack to include only the necessary functions, resulting in smaller application bundles. While the original author has moved on, the project is actively maintained by a community of volunteers who oversee code reviews, issues, and ensure its continued functionality and stability. It ships with TypeScript type definitions, providing a robust development experience.
npm install isomorphic-gitVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to clone a Git repository using isomorphic-git in a Node.js environment, showing the necessary setup for the file system client.
Refer to the v1.0.0 Release Notes on GitHub (https://github.com/isomorphic-git/isomorphic-git/releases/tag/v1.0.0) and the accompanying blog post for detailed migration guides.
For Node.js, wrap `node:fs/promises` into the expected interface. For browser environments, use `@isomorphic-git/lightning-fs` or another IndexedDB-backed file system, or provide your own custom implementation.
Consider contributing new features or funding their development if they are critical to your use case. Monitor the GitHub issues for community-driven initiatives.
Review the documentation for supported protocols and authentication methods. For complex scenarios, ensure your environment provides the necessary credentials (e.g., `http.auth` callbacks, SSH agent) or fallbacks.
Ensure your Node.js environment meets or exceeds the specified `engines` requirement. Upgrade Node.js if necessary.
Ensure your `fs` client is properly set up and points to a valid storage location. Verify directory paths and permissions. For Node.js, make sure initial directories are created (`fs.promises.mkdir(dir, { recursive: true })`). For browsers, confirm `lightning-fs` has initialized its IndexedDB store.Ensure your `fs` client object has a `promises` property that exposes async file system methods (`readFile`, `writeFile`, `mkdir`, `readdir`, `rm`, `stat`, `lstat`). If using TypeScript, explicitly type your `fs` object with `FsClient` to catch mismatches during development.
For common public repositories, use `https://` URLs. For `ssh://` URLs, you need to configure an `ssh` agent and provide a `url` parameter callback to handle the SSH connection. `git://` is generally not supported.