Registry / devops / isomorphic-git

isomorphic-git

JSON →
library1.37.5jsnpmunverified

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-git
INSTALL
IMPORT
SIG · ISOMORPHIC-GIT
I
isomorphic-git
devopsjavascriptv1.37.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

clone
import { clone } from 'isomorphic-git'
const clone = require('isomorphic-git').clone
isomorphic-git primarily exposes named exports. While CommonJS `require` might work in older Node versions or bundled applications, ESM `import` is the recommended and best-supported pattern, especially with TypeScript.
init
import { init } from 'isomorphic-git'
import init from 'isomorphic-git'
Functions like `init` are named exports, not the default export. Attempting a default import will fail.
log
import { log } from 'isomorphic-git'
import { default as log } from 'isomorphic-git'
Many core Git commands are exposed as individual named functions, promoting tree-shaking for optimized bundle sizes.
FsClient
import { FsClient } from 'isomorphic-git'
This is a TypeScript type definition for the file system interface expected by isomorphic-git functions. It's crucial for type-checking when providing a custom FS implementation.

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.

import { clone } from 'isomorphic-git'; import * as fs from 'node:fs/promises'; // For Node.js. For browser, use lightning-fs or similar. interface FsClient { promises: { readFile(path: string, options?: { encoding?: string; flag?: string }): Promise<string | Buffer>; writeFile(path: string, data: string | Uint8Array, options?: { encoding?: string; mode?: number | string; flag?: string }): Promise<void>; mkdir(path: string, options?: { recursive?: boolean }): Promise<string | undefined>; readdir(path: string): Promise<string[]>; rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>; stat(path: string): Promise<fs.Stats>; lstat(path: string): Promise<fs.Stats>; // ... other methods as needed by isomorphic-git }; } // Create an isomorphic-git compatible file system client using Node's fs/promises const nodeFsClient: FsClient = { promises: { readFile: fs.readFile, writeFile: fs.writeFile, mkdir: (path, options) => fs.mkdir(path, { recursive: true, ...options }), // Ensure recursive by default readdir: fs.readdir, rm: (path, options) => fs.rm(path, { recursive: true, force: true, ...options }), // Ensure recursive & force by default stat: fs.stat, lstat: fs.lstat } }; async function performClone() { const dir = './my-cloned-repo'; console.log(`Cloning into ${dir}...`); try { await clone({ fs: nodeFsClient, // Provide the file system client dir: dir, url: 'https://github.com/isomorphic-git/isomorphic-git-autotests.git', // A small test repo ref: 'main', singleBranch: true, depth: 1 }); console.log('Repository cloned successfully!'); // You can now read files, commit, etc. const files = await nodeFsClient.promises.readdir(dir); console.log('Files in cloned repo:', files); } catch (error) { console.error('Error during clone:', error); } } performClone();
Debug
Known issues
breakingWhen upgrading from version 0.x to 1.x, significant breaking changes were introduced to the API. Developers should consult the official release notes for `v1.0.0` to understand the necessary migration steps.
fix
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.
affects: >=1.0.0
gotchaisomorphic-git requires a compatible file system abstraction (`fs` object) to perform most operations, as it interacts directly with a virtual or actual '.git' directory. This `fs` object is a mandatory parameter for almost all `isomorphic-git` functions.
fix
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.
affects: >=0.x
gotchaThe project's 'maintenance' status means that while it is actively maintained by volunteers for bug fixes and stability, new features are primarily driven by community contributions. Expecting rapid implementation of new features by maintainers alone may lead to disappointment.
fix
Consider contributing new features or funding their development if they are critical to your use case. Monitor the GitHub issues for community-driven initiatives.
affects: >=1.0.0
gotchaisomorphic-git works with 'plain' Git over HTTP(S) and SSH (with proper agent configuration). However, advanced Git features, custom protocols, or specific authentication mechanisms may require additional setup or might not be fully supported out-of-the-box compared to the native Git client.
fix
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.
affects: >=0.x
gotchaThe Node.js `engines` requirement is `>=14.17`. Running isomorphic-git in older Node.js versions might lead to compatibility issues, especially with modern ES module usage and `fs/promises` features.
fix
Ensure your Node.js environment meets or exceeds the specified `engines` requirement. Upgrade Node.js if necessary.
affects: <14.17
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, open '...' (or similar file system errors)
The provided file system (`fs` object) is not correctly initialized, or the specified directory/file path does not exist or is inaccessible within the virtual file system.
fix
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.
TypeError: Cannot read properties of undefined (reading 'promises') OR Argument of type 'typeof import("node:fs")' is not assignable to parameter of type 'FsClient'.
The `fs` object passed to isomorphic-git functions does not conform to the expected `FsClient` interface, particularly lacking the `promises` property or required methods within it.
fix
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.
Error: Unknown transport 'git://' OR Unsupported protocol: 'ssh://'
The `url` provided for operations like `clone` or `fetch` uses a Git protocol (e.g., `git://` or `ssh://`) that isomorphic-git either does not support natively or requires additional setup.
fix
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.
Upgrade
Version history
1.37.5latest on npm
Audit
Dependencies
@isomorphic-git/lightning-fsoptionalRequired for browser environments to provide a file system abstraction for repository operations (e.g., IndexedDB backed FS). For Node.js, `node:fs/promises` or a similar wrapper is used.
Agent activity
40 hits · last 30 days
node
38
OpenAI (training)
1
Resources
isomorphic-git — npm install isomorphic-git · libregistry