CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-isomorphic-git

A pure JavaScript implementation of git for node and browsers

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

isomorphic-git

isomorphic-git is a pure JavaScript reimplementation of Git that provides 100% interoperability with the canonical Git implementation. It works in both Node.js and browser environments without requiring native C++ modules, making it ideal for web applications and cross-platform JavaScript projects.

Package Information

  • Package Name: isomorphic-git
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install isomorphic-git

Core Imports

import git from "isomorphic-git";

Named imports for tree-shaking:

import { clone, add, commit, push, pull } from "isomorphic-git";

CommonJS:

const git = require("isomorphic-git");
const { clone, add, commit } = require("isomorphic-git");

HTTP clients:

// Node.js
import http from "isomorphic-git/http/node";

// Browser
import http from "isomorphic-git/http/web";

Basic Usage

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";
import fs from "fs";

// Clone a repository
await git.clone({
  fs,
  http,
  dir: "/path/to/repo",
  url: "https://github.com/user/repo.git"
});

// Make changes and commit
await git.add({ fs, dir: "/path/to/repo", filepath: "file.txt" });
await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Add file.txt",
  author: {
    name: "Your Name",
    email: "you@example.com"
  }
});

Architecture

isomorphic-git is built around several key design principles:

  • Isomorphic Design: Same API works in Node.js and browsers by abstracting file system and HTTP operations
  • Modular Architecture: Individual functions can be imported separately for smaller bundles
  • Pure JavaScript: No native dependencies, works everywhere JavaScript runs
  • Git Compatibility: Operates directly on standard .git directories for full interoperability
  • Plugin System: Supports pluggable file systems and HTTP clients

Capabilities

Repository Management

Core operations for initializing, cloning, and managing Git repositories.

function init(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  bare?: boolean;
  defaultBranch?: string;
}): Promise<void>;

function clone(args: {
  fs: FsClient;
  http: HttpClient;
  dir: string;
  gitdir?: string;
  url: string;
  corsProxy?: string;
  ref?: string;
  singleBranch?: boolean;
  noCheckout?: boolean;
  noTags?: boolean;
  remote?: string;
  depth?: number;
  since?: Date;
  exclude?: string[];
  relative?: boolean;
  headers?: Record<string, string>;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
  onPostCheckout?: PostCheckoutCallback;
  cache?: object;
  nonBlocking?: boolean;
  batchSize?: number;
}): Promise<void>;

function version(): string;

Repository Operations

Working Directory Operations

Functions for staging files, checking status, and managing the working directory.

function add(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string | string[];
  cache?: object;
  force?: boolean;
  parallel?: boolean;
}): Promise<void>;

function remove(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
  cache?: object;
}): Promise<void>;

function status(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
  cache?: object;
}): Promise<'ignored' | 'unmodified' | '*modified' | '*deleted' | '*added' | 'absent' | 'modified' | 'deleted' | 'added' | '*unmodified' | '*absent' | '*undeleted' | '*undeletemodified'>;

function statusMatrix(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  filepaths?: string[];
  filter?: (f: string) => boolean;
  cache?: object;
  ignored?: boolean;
}): Promise<Array<[string, number, number, number]>>;

Working Directory

Commit Operations

Creating commits, reading commit history, and commit-related operations.

function commit(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  message?: string;
  author?: PersonObject;
  committer?: PersonObject;
  signingKey?: string;
  onSign?: SignCallback;
  amend?: boolean;
  dryRun?: boolean;
  noUpdateBranch?: boolean;
  ref?: string;
  parent?: string[];
  tree?: string;
  cache?: object;
}): Promise<string>;

function log(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  depth?: number;
  since?: Date;
  until?: Date;
  force?: boolean;
  follow?: boolean;
  cache?: object;
}): Promise<ReadCommitResult[]>;

Commit Operations

Branch Management

Creating, switching, listing, and managing branches.

function branch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  object?: string;
  checkout?: boolean;
  force?: boolean;
}): Promise<void>;

function checkout(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  remote?: string;
  noCheckout?: boolean;
  force?: boolean;
  track?: boolean;
  filepaths?: string[];
  cache?: object;
  onProgress?: ProgressCallback;
}): Promise<void>;

function currentBranch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  fullname?: boolean;
}): Promise<string | undefined>;

function listBranches(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  remote?: string;
}): Promise<string[]>;

Branch Management

Remote Operations

Fetching, pushing, and managing remote repositories.

function fetch(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  url?: string;
  remote?: string;
  ref?: string;
  remoteRef?: string;
  depth?: number;
  since?: Date;
  exclude?: string[];
  relative?: boolean;
  tags?: boolean;
  singleBranch?: boolean;
  headers?: Record<string, string>;
  corsProxy?: string;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
  cache?: object;
}): Promise<FetchResult>;

function push(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  url?: string;
  remote?: string;
  ref?: string;
  remoteRef?: string;
  force?: boolean;
  delete?: boolean;
  corsProxy?: string;
  headers?: Record<string, string>;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
}): Promise<PushResult>;

function pull(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  url?: string;
  remote?: string;
  remoteRef?: string;
  corsProxy?: string;
  headers?: Record<string, string>;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
  fastForward?: boolean;
  noUpdateBranch?: boolean;
  cache?: object;
}): Promise<void>;

Remote Operations

Configuration Management

Reading and writing Git configuration values.

function getConfig(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  path: string;
}): Promise<any>;

function getConfigAll(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  path: string;
}): Promise<any[]>;

function setConfig(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  path: string;
  value: any;
  append?: boolean;
}): Promise<void>;

Configuration

Object Operations

Low-level operations for reading and writing Git objects (blobs, commits, trees, tags).

function readObject(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  format?: string;
  filepath?: string;
  encoding?: string;
}): Promise<ReadObjectResult>;

function writeObject(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  type: string;
  object: Uint8Array;
  format?: string;
  oid?: string;
  encoding?: string;
}): Promise<string>;

function hashBlob(args: {
  object: Uint8Array;
}): Promise<string>;

Object Operations

Reference Management

Managing Git references (branches, tags, HEAD).

function resolveRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  depth?: number;
}): Promise<string>;

function expandRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
}): Promise<string>;

function listRefs(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
}): Promise<string[]>;

function writeRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  value: string;
  force?: boolean;
  symbolic?: boolean;
}): Promise<void>;

Reference Management

Advanced Operations

Advanced Git operations including merging, rebasing, and repository walking.

function merge(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ours?: string;
  theirs: string;
  fastForward?: boolean;
  noUpdateBranch?: boolean;
  dryRun?: boolean;
  abortOnConflict?: boolean;
  message?: string;
  author?: PersonObject;
  committer?: PersonObject;
  signingKey?: string;
  onSign?: SignCallback;
  cache?: object;
}): Promise<MergeResult>;

function walk(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  trees: Walker[];
  map?: (filepath: string, entries: WalkerEntry[]) => any;
  reduce?: (parent: any, children: any[]) => any;
  iterate?: (entries: WalkerEntry[], children: any[]) => any;
  cache?: object;
}): Promise<any>;

Advanced Operations

Types

interface FsClient {
  promises: {
    readFile(filepath: string, options?: any): Promise<Buffer | string>;
    writeFile(filepath: string, data: any, options?: any): Promise<void>;
    mkdir(dir: string, options?: any): Promise<void>;
    rmdir(dir: string, options?: any): Promise<void>;
    unlink(filepath: string): Promise<void>;
    stat(filepath: string): Promise<Stats>;
    lstat(filepath: string): Promise<Stats>;
    readdir(dir: string): Promise<string[]>;
    readlink(filepath: string): Promise<string>;
    symlink(target: string, filepath: string): Promise<void>;
    chmod(filepath: string, mode: number): Promise<void>;
  };
}

interface HttpClient {
  request(args: GitHttpRequest): Promise<GitHttpResponse>;
}

interface PersonObject {
  name?: string;
  email?: string;
  timestamp?: number;
  timezoneOffset?: number;
}

interface GitHttpRequest {
  url: string;
  method?: string;
  headers?: Record<string, string>;
  body?: Uint8Array | AsyncIterable<Uint8Array>;
  onProgress?: ProgressCallback;
  agent?: any;
}

interface GitHttpResponse {
  url: string;
  method?: string;
  statusCode: number;
  statusMessage: string;
  body: AsyncIterable<Uint8Array>;
  headers: Record<string, string>;
}

type ProgressCallback = (progress: ProgressEvent) => void | Promise<void>;
type MessageCallback = (message: string) => void | Promise<void>;
type AuthCallback = (url: string, auth: AuthOptions) => AuthResult | Promise<AuthResult>;
type AuthFailureCallback = (url: string, auth: AuthOptions) => void | Promise<void>;
type AuthSuccessCallback = (url: string, auth: AuthOptions) => void | Promise<void>;
type PostCheckoutCallback = () => void | Promise<void>;
type SignCallback = (args: SignArgs) => string | Promise<string>;

// Walker constants for repository traversal
const STAGE: Walker;  // Git index walker
const TREE: Walker;   // Git tree walker  
const WORKDIR: Walker; // Working directory walker

Error Handling

isomorphic-git provides a comprehensive set of error classes for different failure conditions:

// Import all error classes
import { Errors } from "isomorphic-git";

// Common error types
class NotFoundError extends Error {}
class InvalidRefNameError extends Error {}
class CheckoutConflictError extends Error {}
class MergeConflictError extends Error {}
class PushRejectedError extends Error {}
class HttpError extends Error {}
class GitPushError extends Error {}

Error Handling

CLI Tool

isomorphic-git includes a command-line interface for testing and basic operations:

# Install globally
npm install -g isomorphic-git

# Use the isogit command
isogit clone https://github.com/user/repo.git ./repo
isogit status --dir ./repo
isogit log --dir ./repo

Browser Considerations

When using isomorphic-git in browsers:

  • Use isomorphic-git/http/web for HTTP client
  • Provide a compatible file system like LightningFS
  • Use CORS proxy for cross-origin requests: corsProxy: "https://cors.isomorphic-git.org"
  • Consider using service workers for background operations
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/isomorphic-git@1.33.x
Publish Source
CLI
Badge
tessl/npm-isomorphic-git badge