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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Commit Operations

Name: tessl/npm-isomorphic-git
Author: tessl

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

Capabilities

Create Commit

Creates a new commit with the staged changes.

/**
 * Create a new commit
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.message - Commit message (required unless amending)
 * @param args.author - Author information
 * @param args.committer - Committer information (defaults to author)
 * @param args.signingKey - PGP signing key
 * @param args.onSign - Signing callback
 * @param args.amend - Replace the last commit
 * @param args.dryRun - Simulate commit without creating it
 * @param args.noUpdateBranch - Don't update branch pointer
 * @param args.ref - Branch reference to commit to
 * @param args.parent - Parent commit SHA(s)
 * @param args.tree - Tree SHA to use
 * @param args.cache - Cache object
 * @returns Promise resolving to new commit SHA
 */
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>;

Usage Examples:

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

// Basic commit
const sha = await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Add new feature",
  author: {
    name: "John Doe",
    email: "john@example.com"
  }
});
console.log("Created commit:", sha);

// Commit with custom timestamp
await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Backdate this commit",
  author: {
    name: "John Doe",
    email: "john@example.com",
    timestamp: Math.floor(Date.parse("2023-01-01") / 1000)
  }
});

// Amend the last commit
await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Updated commit message",
  amend: true
});

// Dry run to test commit
const wouldCreateSha = await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Test commit",
  author: { name: "Test", email: "test@example.com" },
  dryRun: true
});

Read Commit History

Retrieves commit history from the repository.

/**
 * Get commit history
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Starting reference (defaults to HEAD)
 * @param args.depth - Maximum number of commits to return
 * @param args.since - Only commits after this date
 * @param args.until - Only commits before this date
 * @param args.force - Don't stop on errors
 * @param args.follow - Follow file renames
 * @param args.cache - Cache object
 * @returns Promise resolving to array of commit objects
 */
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[]>;

Usage Examples:

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

// Get last 10 commits
const commits = await git.log({
  fs,
  dir: "/path/to/repo",
  depth: 10
});

for (const commit of commits) {
  console.log(`${commit.oid.slice(0, 8)} ${commit.commit.message}`);
  console.log(`Author: ${commit.commit.author.name} <${commit.commit.author.email}>`);
  console.log(`Date: ${new Date(commit.commit.author.timestamp * 1000)}`);
  console.log("---");
}

// Get commits from specific branch
const branchCommits = await git.log({
  fs,
  dir: "/path/to/repo",
  ref: "feature-branch",
  depth: 5
});

// Get commits in date range
const recentCommits = await git.log({
  fs,
  dir: "/path/to/repo",
  since: new Date("2023-01-01"),
  until: new Date("2023-12-31")
});

Read Commit Object

Reads detailed information about a specific commit.

/**
 * Read a commit object
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Commit SHA
 * @param args.cache - Cache object
 * @returns Promise resolving to commit object
 */
function readCommit(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  cache?: object;
}): Promise<ReadCommitResult>;

Usage Example:

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

const commit = await git.readCommit({
  fs,
  dir: "/path/to/repo",
  oid: "abc123..."
});

console.log("Message:", commit.commit.message);
console.log("Author:", commit.commit.author.name);
console.log("Tree:", commit.commit.tree);
console.log("Parents:", commit.commit.parent);

Write Commit Object

Creates a commit object in the repository.

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

Usage Example:

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

const commitSha = await git.writeCommit({
  fs,
  dir: "/path/to/repo",
  commit: {
    message: "Manual commit creation",
    tree: "tree-sha-here",
    parent: ["parent-commit-sha"],
    author: {
      name: "Manual Author",
      email: "manual@example.com",
      timestamp: Math.floor(Date.now() / 1000),
      timezoneOffset: new Date().getTimezoneOffset()
    },
    committer: {
      name: "Manual Author", 
      email: "manual@example.com",
      timestamp: Math.floor(Date.now() / 1000),
      timezoneOffset: new Date().getTimezoneOffset()
    }
  }
});

Find Merge Base

Finds the common ancestor commit between two commits.

/**
 * Find the merge base between commits
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oids - Array of commit SHAs to find base for
 * @param args.cache - Cache object
 * @returns Promise resolving to merge base commit SHA
 */
function findMergeBase(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oids: string[];
  cache?: object;
}): Promise<string[]>;

Usage Example:

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

const mergeBase = await git.findMergeBase({
  fs,
  dir: "/path/to/repo",
  oids: ["commit-sha-1", "commit-sha-2"]
});
console.log("Merge base:", mergeBase[0]);

Check Descendant Relationship

Checks if one commit is a descendant of another.

/**
 * Check if one commit is descendant of another
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oid - Potential descendant commit SHA
 * @param args.ancestor - Potential ancestor commit SHA
 * @param args.depth - Maximum depth to search
 * @param args.cache - Cache object
 * @returns Promise resolving to true if descendant relationship exists
 */
function isDescendent(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oid: string;
  ancestor: string;
  depth?: number;
  cache?: object;
}): Promise<boolean>;

Usage Example:

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

const isDesc = await git.isDescendent({
  fs,
  dir: "/path/to/repo",
  oid: "newer-commit-sha",
  ancestor: "older-commit-sha"
});
console.log(isDesc ? "Is descendant" : "Not descendant");

Types

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

interface CommitObject {
  message: string;
  tree: string;
  parent: string[];
  author: PersonObject;
  committer: PersonObject;
  gpgsig?: string;
}

interface ReadCommitResult {
  oid: string;
  commit: CommitObject;
  payload: string;
}

type SignCallback = (args: {
  payload: string;
  secretKey: string;
}) => string | Promise<string>;