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

Branch Management

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

Creating, switching, listing, and managing branches.

Capabilities

Create Branch

Creates a new branch pointing to a specific commit.

/**
 * Create a new branch
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Branch name to create
 * @param args.object - Commit SHA to point branch at (defaults to HEAD)
 * @param args.checkout - Whether to checkout the new branch
 * @param args.force - Overwrite existing branch
 * @returns Promise resolving when branch is created
 */
function branch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  object?: string;
  checkout?: boolean;
  force?: boolean;
}): Promise<void>;

Usage Examples:

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

// Create a new branch from current HEAD
await git.branch({
  fs,
  dir: "/path/to/repo",
  ref: "feature-branch"
});

// Create and checkout new branch
await git.branch({
  fs,
  dir: "/path/to/repo", 
  ref: "feature-branch",
  checkout: true
});

// Create branch from specific commit
await git.branch({
  fs,
  dir: "/path/to/repo",
  ref: "hotfix-branch",
  object: "abc123..."
});

// Force create branch (overwrite existing)
await git.branch({
  fs,
  dir: "/path/to/repo",
  ref: "existing-branch",
  force: true
});

Checkout Branch or Files

Switches to a different branch or checks out specific files.

/**
 * Checkout a branch or specific files
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Branch name or commit to checkout
 * @param args.remote - Remote name for tracking branches
 * @param args.noCheckout - Don't update working directory
 * @param args.force - Overwrite local changes
 * @param args.track - Set up tracking relationship
 * @param args.filepaths - Specific files to checkout
 * @param args.cache - Cache object
 * @param args.onProgress - Progress callback
 * @returns Promise resolving when checkout completes
 */
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>;

Usage Examples:

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

// Checkout existing branch
await git.checkout({
  fs,
  dir: "/path/to/repo",
  ref: "feature-branch"
});

// Checkout remote branch and set up tracking
await git.checkout({
  fs,
  dir: "/path/to/repo",
  ref: "feature-branch",
  remote: "origin",
  track: true
});

// Checkout specific commit (detached HEAD)
await git.checkout({
  fs,
  dir: "/path/to/repo",
  ref: "abc123..."
});

// Checkout specific files from another branch
await git.checkout({
  fs,
  dir: "/path/to/repo",
  ref: "main",
  filepaths: ["src/config.js", "README.md"]
});

// Force checkout (discard local changes)
await git.checkout({
  fs,
  dir: "/path/to/repo",
  ref: "main",
  force: true
});

Get Current Branch

Returns the name of the currently checked out branch.

/**
 * Get the current branch name
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.fullname - Return full reference name
 * @returns Promise resolving to branch name or undefined if detached HEAD
 */
function currentBranch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  fullname?: boolean;
}): Promise<string | undefined>;

Usage Examples:

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

// Get current branch name
const branch = await git.currentBranch({
  fs,
  dir: "/path/to/repo"
});
console.log("Current branch:", branch); // "main"

// Get full reference name
const fullRef = await git.currentBranch({
  fs,
  dir: "/path/to/repo",
  fullname: true
});
console.log("Full ref:", fullRef); // "refs/heads/main"

// Handle detached HEAD
const detachedBranch = await git.currentBranch({
  fs,
  dir: "/path/to/repo"
});
if (detachedBranch === undefined) {
  console.log("In detached HEAD state");
}

List Branches

Lists all local or remote branches.

/**
 * List branches
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path  
 * @param args.remote - Remote name to list remote branches
 * @returns Promise resolving to array of branch names
 */
function listBranches(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  remote?: string;
}): Promise<string[]>;

Usage Examples:

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

// List all local branches
const localBranches = await git.listBranches({
  fs,
  dir: "/path/to/repo"
});
console.log("Local branches:", localBranches);
// ["main", "feature-branch", "hotfix"]

// List remote branches
const remoteBranches = await git.listBranches({
  fs,
  dir: "/path/to/repo",
  remote: "origin"
});
console.log("Remote branches:", remoteBranches);
// ["main", "develop", "feature-1"]

// List all remotes and their branches
const remotes = await git.listRemotes({ fs, dir: "/path/to/repo" });
for (const remote of remotes) {
  const branches = await git.listBranches({
    fs,
    dir: "/path/to/repo",
    remote: remote.remote
  });
  console.log(`${remote.remote}:`, branches);
}

Delete Branch

Deletes a local branch.

/**
 * Delete a branch
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Branch name to delete
 * @returns Promise resolving when branch is deleted
 */
function deleteBranch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
}): Promise<void>;

Usage Example:

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

// Delete a branch
await git.deleteBranch({
  fs,
  dir: "/path/to/repo",
  ref: "old-feature-branch"
});

Rename Branch

Renames a branch.

/**
 * Rename a branch
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.oldref - Current branch name
 * @param args.newref - New branch name
 * @param args.checkout - Whether to checkout the renamed branch
 * @returns Promise resolving when branch is renamed
 */
function renameBranch(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  oldref: string;
  newref: string;
  checkout?: boolean;
}): Promise<void>;

Usage Example:

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

// Rename a branch
await git.renameBranch({
  fs,
  dir: "/path/to/repo",
  oldref: "old-branch-name",
  newref: "new-branch-name"
});

// Rename current branch
await git.renameBranch({
  fs,
  dir: "/path/to/repo",
  oldref: "current-branch",
  newref: "renamed-branch",
  checkout: true
});

Fast Forward Merge

Performs a fast-forward merge to move a branch pointer.

/**
 * Fast-forward a branch
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Branch to fast-forward
 * @param args.oid - Target commit SHA
 * @returns Promise resolving when fast-forward completes
 */
function fastForward(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  oid: string;
}): Promise<void>;

Usage Example:

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

// Fast-forward current branch to latest commit from remote
const commits = await git.log({
  fs,
  dir: "/path/to/repo",
  ref: "origin/main",
  depth: 1
});

await git.fastForward({
  fs,
  dir: "/path/to/repo",
  ref: "main",
  oid: commits[0].oid
});

Branch Workflow Examples

Create Feature Branch Workflow

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

// Start from main branch
await git.checkout({ fs, dir: "/path/to/repo", ref: "main" });

// Create and checkout feature branch
await git.branch({
  fs,
  dir: "/path/to/repo",
  ref: "feature/new-component",
  checkout: true
});

// Work on feature...
// Stage and commit changes
await git.add({ fs, dir: "/path/to/repo", filepath: "src/component.js" });
await git.commit({
  fs,
  dir: "/path/to/repo",
  message: "Add new component",
  author: { name: "Developer", email: "dev@example.com" }
});

Switch Between Branches

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

// Check current branch
const current = await git.currentBranch({ fs, dir: "/path/to/repo" });
console.log("Currently on:", current);

// Switch to different branch
await git.checkout({ fs, dir: "/path/to/repo", ref: "develop" });

// List all branches to see options
const branches = await git.listBranches({ fs, dir: "/path/to/repo" });
console.log("Available branches:", branches);