{"id":11110,"library":"isomorphic-git","title":"isomorphic-git: Pure JavaScript Git","description":"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.","status":"maintenance","version":"1.37.5","language":"javascript","source_language":"en","source_url":"https://github.com/isomorphic-git/isomorphic-git","tags":["javascript","git","isomorphic","typescript"],"install":[{"cmd":"npm install isomorphic-git","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-git","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-git","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"@isomorphic-git/lightning-fs","optional":true}],"imports":[{"note":"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.","wrong":"const clone = require('isomorphic-git').clone","symbol":"clone","correct":"import { clone } from 'isomorphic-git'"},{"note":"Functions like `init` are named exports, not the default export. Attempting a default import will fail.","wrong":"import init from 'isomorphic-git'","symbol":"init","correct":"import { init } from 'isomorphic-git'"},{"note":"Many core Git commands are exposed as individual named functions, promoting tree-shaking for optimized bundle sizes.","wrong":"import { default as log } from 'isomorphic-git'","symbol":"log","correct":"import { log } from 'isomorphic-git'"},{"note":"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.","symbol":"FsClient","correct":"import { FsClient } from 'isomorphic-git'"}],"quickstart":{"code":"import { clone } from 'isomorphic-git';\nimport * as fs from 'node:fs/promises'; // For Node.js. For browser, use lightning-fs or similar.\n\ninterface FsClient {\n  promises: {\n    readFile(path: string, options?: { encoding?: string; flag?: string }): Promise<string | Buffer>;\n    writeFile(path: string, data: string | Uint8Array, options?: { encoding?: string; mode?: number | string; flag?: string }): Promise<void>;\n    mkdir(path: string, options?: { recursive?: boolean }): Promise<string | undefined>;\n    readdir(path: string): Promise<string[]>;\n    rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;\n    stat(path: string): Promise<fs.Stats>;\n    lstat(path: string): Promise<fs.Stats>;\n    // ... other methods as needed by isomorphic-git\n  };\n}\n\n// Create an isomorphic-git compatible file system client using Node's fs/promises\nconst nodeFsClient: FsClient = {\n  promises: {\n    readFile: fs.readFile,\n    writeFile: fs.writeFile,\n    mkdir: (path, options) => fs.mkdir(path, { recursive: true, ...options }), // Ensure recursive by default\n    readdir: fs.readdir,\n    rm: (path, options) => fs.rm(path, { recursive: true, force: true, ...options }), // Ensure recursive & force by default\n    stat: fs.stat,\n    lstat: fs.lstat\n  }\n};\n\nasync function performClone() {\n  const dir = './my-cloned-repo';\n  console.log(`Cloning into ${dir}...`);\n  try {\n    await clone({\n      fs: nodeFsClient, // Provide the file system client\n      dir: dir,\n      url: 'https://github.com/isomorphic-git/isomorphic-git-autotests.git', // A small test repo\n      ref: 'main',\n      singleBranch: true,\n      depth: 1\n    });\n    console.log('Repository cloned successfully!');\n    // You can now read files, commit, etc.\n    const files = await nodeFsClient.promises.readdir(dir);\n    console.log('Files in cloned repo:', files);\n  } catch (error) {\n    console.error('Error during clone:', error);\n  }\n}\n\nperformClone();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"isomorphic-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.","severity":"gotcha","affected_versions":">=0.x"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"isomorphic-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.","severity":"gotcha","affected_versions":">=0.x"},{"fix":"Ensure your Node.js environment meets or exceeds the specified `engines` requirement. Upgrade Node.js if necessary.","message":"The 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.","severity":"gotcha","affected_versions":"<14.17"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: ENOENT: no such file or directory, open '...' (or similar file system errors)"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'promises') OR Argument of type 'typeof import(\"node:fs\")' is not assignable to parameter of type 'FsClient'."},{"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.","cause":"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.","error":"Error: Unknown transport 'git://' OR Unsupported protocol: 'ssh://'"}],"ecosystem":"npm"}