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

object-operations.mddocs/

Object Operations

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

Capabilities

Read Git Object

Reads any Git object from the repository.

/**
 * Read a Git object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Object ID (SHA-1 hash)
 * @param args.format - Object format ('content', 'wrapped', 'deflated', 'parsed')
 * @param args.filepath - File path for blob objects
 * @param args.encoding - Text encoding for content
 * @returns Promise resolving to object data
 */
function readObject(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  format?: string;
  filepath?: string;
  encoding?: string;
}): Promise<ReadObjectResult>;

Usage Examples:

import git from "isomorphic-git";
import fs from "fs";

// Read any object by SHA
const object = await git.readObject({
  fs,
  dir: "/path/to/repo",
  oid: "abc123...",
  format: "parsed"
});

console.log("Object type:", object.type);
console.log("Object content:", object.object);

// Read object content as string
const textObject = await git.readObject({
  fs,
  dir: "/path/to/repo", 
  oid: "def456...",
  format: "content",
  encoding: "utf8"
});
console.log("Content:", textObject.object);

Write Git Object

Writes a Git object to the repository.

/**
 * Write a Git object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.type - Object type ('blob', 'tree', 'commit', 'tag')
 * @param args.object - Object data as Uint8Array
 * @param args.format - Input format ('content', 'wrapped', 'deflated', 'parsed')
 * @param args.oid - Expected object ID for verification
 * @param args.encoding - Text encoding for content
 * @returns Promise resolving to object SHA
 */
function writeObject(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  type: string;
  object: Uint8Array;
  format?: string;
  oid?: string;
  encoding?: string;
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

// Write a blob object
const content = new TextEncoder().encode("Hello, World!");
const blobSha = await git.writeObject({
  fs,
  dir: "/path/to/repo",
  type: "blob",
  object: content
});
console.log("Created blob:", blobSha);

Read Blob Object

Reads a blob (file content) object.

/**
 * Read a blob object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Blob object ID
 * @param args.filepath - File path context
 * @returns Promise resolving to blob data
 */
function readBlob(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  filepath?: string;
}): Promise<ReadBlobResult>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const blob = await git.readBlob({
  fs,
  dir: "/path/to/repo",
  oid: "blob-sha-here"
});

console.log("Blob content:", new TextDecoder().decode(blob.blob));

Write Blob Object

Creates a blob object from data.

/**
 * Write a blob object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.blob - Blob data as Uint8Array
 * @returns Promise resolving to blob SHA
 */
function writeBlob(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  blob: Uint8Array;
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const fileContent = await fs.promises.readFile("./myfile.txt");
const blobSha = await git.writeBlob({
  fs,
  dir: "/path/to/repo",
  blob: fileContent
});
console.log("Created blob:", blobSha);

Hash Blob Data

Calculates the SHA-1 hash of blob data without writing to repository.

/**
 * Calculate SHA-1 hash of blob data
 * @param args.object - Blob data as Uint8Array
 * @returns Promise resolving to SHA-1 hash
 */
function hashBlob(args: {
  object: Uint8Array;
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";

const content = new TextEncoder().encode("Hello, World!");
const hash = await git.hashBlob({ object: content });
console.log("Hash:", hash);

Read Tree Object

Reads a tree (directory listing) object.

/**
 * Read a tree object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Tree object ID
 * @param args.filepath - File path context
 * @returns Promise resolving to tree entries
 */
function readTree(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  filepath?: string;
}): Promise<ReadTreeResult>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const tree = await git.readTree({
  fs,
  dir: "/path/to/repo",
  oid: "tree-sha-here"
});

for (const entry of tree.tree) {
  console.log(`${entry.mode} ${entry.type} ${entry.oid} ${entry.path}`);
}

Write Tree Object

Creates a tree object.

/**
 * Write a tree object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.tree - Tree entries
 * @returns Promise resolving to tree SHA
 */
function writeTree(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  tree: TreeEntry[];
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const treeSha = await git.writeTree({
  fs,
  dir: "/path/to/repo",
  tree: [
    {
      mode: "100644",
      path: "README.md",
      oid: "blob-sha-here",
      type: "blob"
    },
    {
      mode: "040000", 
      path: "src",
      oid: "subtree-sha-here",
      type: "tree"
    }
  ]
});
console.log("Created tree:", treeSha);

Read Tag Object

Reads an annotated tag object.

/**
 * Read a tag object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Tag object ID
 * @returns Promise resolving to tag data
 */
function readTag(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
}): Promise<ReadTagResult>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const tag = await git.readTag({
  fs,
  dir: "/path/to/repo",
  oid: "tag-sha-here"
});

console.log("Tag name:", tag.tag.tag);
console.log("Tag message:", tag.tag.message);
console.log("Tagged object:", tag.tag.object);
console.log("Tagger:", tag.tag.tagger);

Write Tag Object

Creates an annotated tag object.

/**
 * Write a tag object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.tag - Tag data
 * @returns Promise resolving to tag SHA
 */
function writeTag(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  tag: TagObject;
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

const tagSha = await git.writeTag({
  fs,
  dir: "/path/to/repo",
  tag: {
    object: "commit-sha-here",
    type: "commit",
    tag: "v1.0.0",
    message: "Release version 1.0.0",
    tagger: {
      name: "Tagger Name",
      email: "tagger@example.com",
      timestamp: Math.floor(Date.now() / 1000),
      timezoneOffset: new Date().getTimezoneOffset()
    }
  }
});
console.log("Created tag:", tagSha);

Expand Object ID

Expands abbreviated object IDs to full SHA-1 hashes.

/**
 * Expand abbreviated object ID
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Abbreviated object ID
 * @returns Promise resolving to full object ID
 */
function expandOid(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
}): Promise<string>;

Usage Example:

import git from "isomorphic-git";
import fs from "fs";

// Expand short SHA to full SHA
const fullSha = await git.expandOid({
  fs,
  dir: "/path/to/repo",
  oid: "abc123" // Short SHA
});
console.log("Full SHA:", fullSha); // Full 40-character SHA

Types

interface ReadObjectResult {
  oid: string;
  type: string;
  object: Uint8Array;
  format: string;
  source?: string;
}

interface ReadBlobResult {
  oid: string;
  blob: Uint8Array;
}

interface ReadTreeResult {
  oid: string;
  tree: TreeEntry[];
}

interface ReadTagResult {
  oid: string;
  tag: TagObject;
  payload: string;
}

interface TreeEntry {
  mode: string;
  path: string;
  oid: string;
  type: string;
}

interface TagObject {
  object: string;
  type: string;
  tag: string;
  message: string;
  tagger: PersonObject;
  gpgsig?: string;
}

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

Working with Objects

Create Files and Trees

import git from "isomorphic-git";
import fs from "fs";

// Create blob from file content
const fileContent = new TextEncoder().encode("console.log('Hello, World!');");
const blobSha = await git.writeBlob({
  fs,
  dir: "/path/to/repo",
  blob: fileContent
});

// Create tree with the blob
const treeSha = await git.writeTree({
  fs,
  dir: "/path/to/repo",
  tree: [
    {
      mode: "100644",
      path: "index.js",
      oid: blobSha,
      type: "blob"
    }
  ]
});

console.log("Created blob:", blobSha);
console.log("Created tree:", treeSha);

Read Object Contents

import git from "isomorphic-git";
import fs from "fs";

// Read and display object contents
const object = await git.readObject({
  fs,
  dir: "/path/to/repo",
  oid: "object-sha-here",
  format: "parsed"
});

switch (object.type) {
  case "blob":
    console.log("File content:", new TextDecoder().decode(object.object));
    break;
  case "tree":
    console.log("Directory listing:", object.object);
    break;
  case "commit":
    console.log("Commit data:", object.object);
    break;
  case "tag":
    console.log("Tag data:", object.object);
    break;
}

docs

advanced-operations.md

branch-management.md

commit-operations.md

configuration.md

error-handling.md

index.md

object-operations.md

reference-management.md

remote-operations.md

repository-operations.md

working-directory.md

tile.json