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

Working Directory Operations

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

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

Capabilities

Add Files to Staging

Stages files for commit by adding them to the Git index.

/**
 * Stage a file for commit
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.filepath - Path to file to stage (can be string or string[])
 * @param args.cache - Cache object
 * @param args.force - Add to index even if matches gitignore
 * @param args.parallel - Process each input file in parallel
 * @returns Promise resolving when file is staged
 */
function add(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string | string[];
  cache?: object;
  force?: boolean;
  parallel?: boolean;
}): Promise<void>;

Usage Examples:

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

// Stage a single file
await git.add({
  fs,
  dir: "/path/to/repo",
  filepath: "src/index.js"
});

// Stage multiple files
const files = ["src/index.js", "README.md", "package.json"];
for (const filepath of files) {
  await git.add({ fs, dir: "/path/to/repo", filepath });
}

Remove Files

Removes files from the index and optionally from the working directory.

/**
 * Remove a file from the index and working directory
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.filepath - Path to file to remove
 * @param args.cache - Cache object
 * @returns Promise resolving when file is removed
 */
function remove(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
  cache?: object;
}): Promise<void>;

Usage Example:

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

// Remove a file
await git.remove({
  fs,
  dir: "/path/to/repo",
  filepath: "old-file.js"
});

Check File Status

Returns the status of a single file in the working directory.

/**
 * Get the status of a file
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.filepath - Path to file to check
 * @param args.cache - Cache object
 * @returns Promise resolving to status string
 */
function status(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
  cache?: object;
}): Promise<string>;

Status Values:

"ignored" - File is ignored by .gitignore
"unmodified" - File is unchanged from HEAD commit
"*modified" - File is modified in working directory but not staged
"*deleted" - File is deleted in working directory but not staged
"*added" - File is new in working directory but not staged
"absent" - File not present in HEAD commit, staging area, or working dir
"modified" - File is staged for commit
"deleted" - File is staged for deletion
"added" - File is staged as new
"*unmodified" - Working dir and HEAD commit match, but index differs
"*absent" - File not present in working dir or HEAD commit, but present in the index
"*undeleted" - File was deleted from the index, but is still in the working dir
"*undeletemodified" - File was deleted from the index, but is present with modifications in the working dir

Usage Example:

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

const fileStatus = await git.status({
  fs,
  dir: "/path/to/repo",
  filepath: "src/index.js"
});
console.log(fileStatus); // "*modified"

Status Matrix

Returns detailed status information for multiple files as a matrix.

/**
 * Get detailed status matrix for repository files
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Git reference to compare against (defaults to HEAD)
 * @param args.filepaths - Specific files to check (defaults to all files)
 * @param args.filter - Filter function for files
 * @param args.cache - Cache object
 * @param args.ignored - Whether to include ignored files
 * @returns Promise resolving to array of [filepath, HEAD, WORKDIR, STAGE] tuples
 */
function statusMatrix(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  filepaths?: string[];
  filter?: (filepath: string) => boolean;
  cache?: object;
  ignored?: boolean;
}): Promise<Array<[string, number, number, number]>>;

Matrix Values:

0 = File is absent
1 = File is present
2 = File is present but differs from comparison

Usage Examples:

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

// Get status for all files
const matrix = await git.statusMatrix({
  fs,
  dir: "/path/to/repo"
});

// Process the status matrix
for (const [filepath, HEAD, WORKDIR, STAGE] of matrix) {
  if (HEAD === 1 && WORKDIR === 2 && STAGE === 1) {
    console.log(`${filepath} is modified in working directory`);
  } else if (HEAD === 0 && WORKDIR === 1 && STAGE === 0) {
    console.log(`${filepath} is untracked`);
  } else if (HEAD === 1 && WORKDIR === 1 && STAGE === 2) {
    console.log(`${filepath} is staged for commit`);
  }
}

// Get status for specific files only
const specificMatrix = await git.statusMatrix({
  fs,
  dir: "/path/to/repo",
  filepaths: ["src/index.js", "README.md"]
});

List Files

Lists all files tracked by Git in the repository.

/**
 * List all files in the repository
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Git reference to list files from
 * @param args.cache - Cache object
 * @returns Promise resolving to array of file paths
 */
function listFiles(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  cache?: object;
}): Promise<string[]>;

Usage Examples:

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

// List all files in current HEAD
const files = await git.listFiles({
  fs,
  dir: "/path/to/repo"
});
console.log(files); // ["src/index.js", "README.md", "package.json", ...]

// List files from specific commit
const filesAtCommit = await git.listFiles({
  fs,
  dir: "/path/to/repo",
  ref: "abc123"
});

Check if File is Ignored

Checks whether a file is ignored by .gitignore rules.

/**
 * Check if a file is ignored by .gitignore
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.filepath - Path to file to check
 * @returns Promise resolving to true if ignored, false otherwise
 */
function isIgnored(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
}): Promise<boolean>;

Usage Example:

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

const ignored = await git.isIgnored({
  fs,
  dir: "/path/to/repo",
  filepath: "node_modules/some-package/index.js"
});
console.log(ignored ? "File is ignored" : "File is not ignored");

Reset Index

Resets the index to match a specific tree or commit.

/**
 * Reset the index to match a specific tree
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Reference to reset to
 * @param args.filepaths - Specific files to reset
 * @param args.cache - Cache object
 * @returns Promise resolving when reset is complete
 */
function resetIndex(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  filepaths?: string[];
  cache?: object;
}): Promise<void>;

Usage Examples:

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

// Reset entire index to HEAD
await git.resetIndex({
  fs,
  dir: "/path/to/repo",
  ref: "HEAD"
});

// Reset specific files
await git.resetIndex({
  fs,
  dir: "/path/to/repo",
  ref: "HEAD",
  filepaths: ["src/index.js", "README.md"]
});

Update Index

Updates the index with specific file changes.

/**
 * Update the index with file changes
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.filepath - Path to file to update
 * @param args.oid - Object ID to use
 * @param args.mode - File mode
 * @param args.add - Add file to index
 * @param args.remove - Remove file from index
 * @param args.force - Force update
 * @param args.cache - Cache object
 * @returns Promise resolving when update is complete
 */
function updateIndex(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  filepath: string;
  oid?: string;
  mode?: number;
  add?: boolean;
  remove?: boolean;
  force?: boolean;
  cache?: object;
}): Promise<void>;

Usage Example:

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

// Update index entry for a file
await git.updateIndex({
  fs,
  dir: "/path/to/repo",
  filepath: "src/index.js",
  add: true
});