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

Reference Management

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

Managing Git references (branches, tags, HEAD).

Capabilities

Resolve Reference

Resolves a reference to its target object ID.

/**
 * Resolve a reference to an object ID
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Reference name to resolve
 * @param args.depth - Maximum depth for symbolic references
 * @returns Promise resolving to object ID
 */
function resolveRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  depth?: number;
}): Promise<string>;

Usage Examples:

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

// Resolve HEAD to commit SHA
const headSha = await git.resolveRef({
  fs,
  dir: "/path/to/repo",
  ref: "HEAD"
});
console.log("HEAD points to:", headSha);

// Resolve branch to commit SHA  
const branchSha = await git.resolveRef({
  fs,
  dir: "/path/to/repo",
  ref: "main"
});
console.log("main branch points to:", branchSha);

// Resolve tag to object SHA
const tagSha = await git.resolveRef({
  fs,
  dir: "/path/to/repo",
  ref: "v1.0.0"
});
console.log("v1.0.0 tag points to:", tagSha);

// Resolve with full reference name
const fullRefSha = await git.resolveRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/heads/feature-branch"
});
console.log("refs/heads/feature-branch points to:", fullRefSha);

Expand Reference

Expands a reference name to its full form.

/**
 * Expand a reference name to full form
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Reference name to expand
 * @returns Promise resolving to expanded reference name
 */
function expandRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
}): Promise<string>;

Usage Examples:

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

// Expand branch name
const expandedBranch = await git.expandRef({
  fs,
  dir: "/path/to/repo",
  ref: "main"
});
console.log("Expanded:", expandedBranch); // "refs/heads/main"

// Expand tag name
const expandedTag = await git.expandRef({
  fs,
  dir: "/path/to/repo",
  ref: "v1.0.0"
});
console.log("Expanded:", expandedTag); // "refs/tags/v1.0.0"

// Expand remote branch
const expandedRemote = await git.expandRef({
  fs,
  dir: "/path/to/repo",
  ref: "origin/main"
});
console.log("Expanded:", expandedRemote); // "refs/remotes/origin/main"

List References

Lists all references in the repository.

/**
 * List all references
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @returns Promise resolving to array of reference names
 */
function listRefs(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
}): Promise<string[]>;

Usage Example:

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

const refs = await git.listRefs({
  fs,
  dir: "/path/to/repo"
});

console.log("All references:");
for (const ref of refs) {
  const sha = await git.resolveRef({ fs, dir: "/path/to/repo", ref });
  console.log(`${ref}: ${sha.slice(0, 8)}`);
}

// Filter by type
const branches = refs.filter(ref => ref.startsWith("refs/heads/"));
const tags = refs.filter(ref => ref.startsWith("refs/tags/"));
const remotes = refs.filter(ref => ref.startsWith("refs/remotes/"));

console.log("Branches:", branches);
console.log("Tags:", tags);
console.log("Remotes:", remotes);

Write Reference

Creates or updates a reference.

/**
 * Write a reference
 * @param args.fs - File system client 
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Reference name to write
 * @param args.value - Object ID or symbolic reference target  
 * @param args.force - Force update even if not fast-forward
 * @param args.symbolic - Create symbolic reference
 * @returns Promise resolving when reference is written
 */
function writeRef(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  value: string;
  force?: boolean;
  symbolic?: boolean;
}): Promise<void>;

Usage Examples:

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

// Create new branch reference
await git.writeRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/heads/new-branch",
  value: "commit-sha-here"
});

// Update HEAD to point to different branch (symbolic reference)
await git.writeRef({
  fs,
  dir: "/path/to/repo",
  ref: "HEAD",
  value: "refs/heads/main",
  symbolic: true
});

// Force update reference
await git.writeRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/heads/main",
  value: "new-commit-sha",
  force: true
});

// Create lightweight tag
await git.writeRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/tags/v1.0.1",
  value: "commit-sha-here"
});

Delete Reference

Deletes a reference.

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

Usage Examples:

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

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

// Delete a tag
await git.deleteRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/tags/old-tag"
});

// Delete remote tracking branch
await git.deleteRef({
  fs,
  dir: "/path/to/repo",
  ref: "refs/remotes/origin/deleted-branch"
});

List Tags

Lists all tags in the repository.

/**
 * List all tags
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @returns Promise resolving to array of tag names
 */
function listTags(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
}): Promise<string[]>;

Usage Example:

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

const tags = await git.listTags({
  fs,
  dir: "/path/to/repo"
});

console.log("Available tags:");
for (const tag of tags) {
  console.log(`- ${tag}`);
  
  // Get what the tag points to
  const tagSha = await git.resolveRef({
    fs,
    dir: "/path/to/repo",
    ref: tag
  });
  console.log(`  Points to: ${tagSha.slice(0, 8)}`);
}

Create Tag

Creates a lightweight tag pointing to a commit.

/**
 * Create a lightweight tag
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Tag name
 * @param args.object - Object ID to tag (defaults to HEAD)
 * @param args.force - Overwrite existing tag
 * @returns Promise resolving when tag is created
 */
function tag(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  object?: string;
  force?: boolean;
}): Promise<void>;

Usage Examples:

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

// Create tag pointing to HEAD
await git.tag({
  fs,
  dir: "/path/to/repo",
  ref: "v1.0.0"
});

// Create tag pointing to specific commit
await git.tag({
  fs,
  dir: "/path/to/repo",
  ref: "v0.9.0",
  object: "commit-sha-here"
});

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

Create Annotated Tag

Creates an annotated tag with metadata.

/**
 * Create an annotated tag
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Tag name
 * @param args.message - Tag message
 * @param args.object - Object ID to tag (defaults to HEAD)
 * @param args.tagger - Tagger information
 * @param args.signingKey - PGP signing key
 * @param args.force - Overwrite existing tag
 * @returns Promise resolving when tag is created
 */
function annotatedTag(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  ref: string;
  message: string;
  object?: string;
  tagger?: PersonObject;
  signingKey?: string;
  force?: boolean;
}): Promise<void>;

Usage Example:

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

// Create annotated tag
await git.annotatedTag({
  fs,
  dir: "/path/to/repo",
  ref: "v1.0.0",
  message: "Release version 1.0.0\n\nThis is a major release with new features.",
  tagger: {
    name: "Release Manager",
    email: "releases@example.com"
  }
});

Delete Tag

Deletes a tag.

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

Usage Example:

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

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

Reference Types and Patterns

Branch References

Branch references are stored under refs/heads/:

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

// Full branch reference names
const branches = [
  "refs/heads/main",
  "refs/heads/develop",
  "refs/heads/feature/new-ui"
];

// List all local branches
const refs = await git.listRefs({ fs, dir: "/path/to/repo" });
const localBranches = refs
  .filter(ref => ref.startsWith("refs/heads/"))
  .map(ref => ref.replace("refs/heads/", ""));

console.log("Local branches:", localBranches);

Tag References

Tag references are stored under refs/tags/:

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

// Full tag reference names
const tagRefs = [
  "refs/tags/v1.0.0",
  "refs/tags/v1.1.0", 
  "refs/tags/beta-1"
];

// List all tags
const allTags = await git.listTags({ fs, dir: "/path/to/repo" });
console.log("All tags:", allTags);

Remote Tracking References

Remote tracking references are stored under refs/remotes/:

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

// Remote tracking branch references
const remoteRefs = [
  "refs/remotes/origin/main",
  "refs/remotes/origin/develop",
  "refs/remotes/upstream/main"
];

// List all remote tracking branches
const refs = await git.listRefs({ fs, dir: "/path/to/repo" });
const remoteBranches = refs
  .filter(ref => ref.startsWith("refs/remotes/"))
  .map(ref => ref.replace("refs/remotes/", ""));

console.log("Remote branches:", remoteBranches);

Special References

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

// HEAD - current branch/commit
const head = await git.resolveRef({
  fs,
  dir: "/path/to/repo",
  ref: "HEAD"
});

// Check if HEAD is symbolic (points to branch) or direct (detached)
try {
  const currentBranch = await git.currentBranch({
    fs,
    dir: "/path/to/repo"
  });
  if (currentBranch) {
    console.log("On branch:", currentBranch);
  } else {
    console.log("Detached HEAD at:", head.slice(0, 8));
  }
} catch (err) {
  console.log("Detached HEAD at:", head.slice(0, 8));
}