isomorphic-git: Pure JavaScript Git

1.37.5 · maintenance · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

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();

view raw JSON →