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

remote-operations.mddocs/

Remote Operations

Fetching, pushing, and managing remote repositories.

Capabilities

Fetch from Remote

Downloads objects and references from a remote repository.

/**
 * Fetch updates from remote repository
 * @param args.fs - File system client
 * @param args.http - HTTP client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.url - Remote repository URL
 * @param args.remote - Remote name (defaults to 'origin')
 * @param args.ref - Reference to fetch
 * @param args.remoteRef - Remote reference to fetch
 * @param args.depth - Shallow fetch depth
 * @param args.since - Only fetch commits after date
 * @param args.exclude - References to exclude
 * @param args.relative - Make depth relative to current
 * @param args.tags - Fetch tags
 * @param args.singleBranch - Only fetch single branch
 * @param args.headers - Additional HTTP headers
 * @param args.corsProxy - CORS proxy URL
 * @param args.onProgress - Progress callback
 * @param args.onMessage - Message callback
 * @param args.onAuth - Authentication callback
 * @param args.onAuthFailure - Auth failure callback
 * @param args.onAuthSuccess - Auth success callback
 * @param args.cache - Cache object
 * @returns Promise resolving to fetch result
 */
function fetch(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  url?: string;
  remote?: string;
  ref?: string;
  remoteRef?: string;
  depth?: number;
  since?: Date;
  exclude?: string[];
  relative?: boolean;
  tags?: boolean;
  singleBranch?: boolean;
  headers?: Record<string, string>;
  corsProxy?: string;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
  cache?: object;
}): Promise<FetchResult>;

Usage Examples:

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";
import fs from "fs";

// Basic fetch from origin
const fetchResult = await git.fetch({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin"
});
console.log("Fetch result:", fetchResult);

// Fetch specific branch
await git.fetch({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main"
});

// Shallow fetch with progress tracking
await git.fetch({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  depth: 1,
  onProgress: (event) => {
    console.log(`Progress: ${event.phase} ${event.loaded}/${event.total}`);
  }
});

// Fetch with authentication
await git.fetch({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  onAuth: (url, auth) => {
    return {
      username: process.env.GIT_USERNAME,
      password: process.env.GIT_TOKEN
    };
  }
});

Push to Remote

Uploads local commits to a remote repository.

/**
 * Push changes to remote repository
 * @param args.fs - File system client
 * @param args.http - HTTP client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.url - Remote repository URL
 * @param args.remote - Remote name (defaults to 'origin')
 * @param args.ref - Local reference to push
 * @param args.remoteRef - Remote reference to update
 * @param args.force - Force push (overwrite remote)
 * @param args.delete - Delete remote reference
 * @param args.corsProxy - CORS proxy URL
 * @param args.headers - Additional HTTP headers
 * @param args.onProgress - Progress callback
 * @param args.onMessage - Message callback
 * @param args.onAuth - Authentication callback
 * @param args.onAuthFailure - Auth failure callback
 * @param args.onAuthSuccess - Auth success callback
 * @returns Promise resolving to push result
 */
function push(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  url?: string;
  remote?: string;
  ref?: string;
  remoteRef?: string;
  force?: boolean;
  delete?: boolean;
  corsProxy?: string;
  headers?: Record<string, string>;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
}): Promise<PushResult>;

Usage Examples:

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";
import fs from "fs";

// Basic push to origin
const pushResult = await git.push({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main"
});
console.log("Push result:", pushResult);

// Push with authentication
await git.push({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin", 
  ref: "feature-branch",
  onAuth: () => ({
    username: "your-username",
    password: "your-token"
  })
});

// Force push (dangerous!)
await git.push({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main",
  force: true
});

// Push to different remote branch name
await git.push({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "local-branch",
  remoteRef: "remote-branch"
});

Pull from Remote

Fetches and merges changes from a remote repository.

/**
 * Pull changes from remote repository (fetch + merge)
 * @param args.fs - File system client
 * @param args.http - HTTP client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.ref - Local branch to update
 * @param args.url - Remote repository URL
 * @param args.remote - Remote name
 * @param args.remoteRef - Remote branch to pull from
 * @param args.corsProxy - CORS proxy URL
 * @param args.headers - Additional HTTP headers
 * @param args.onProgress - Progress callback
 * @param args.onMessage - Message callback
 * @param args.onAuth - Authentication callback
 * @param args.onAuthFailure - Auth failure callback
 * @param args.onAuthSuccess - Auth success callback
 * @param args.fastForward - Only allow fast-forward merges
 * @param args.noUpdateBranch - Don't update branch pointer
 * @param args.cache - Cache object
 * @returns Promise resolving when pull completes
 */
function pull(args: {
  fs: FsClient;
  http: HttpClient;
  dir?: string;
  gitdir?: string;
  ref?: string;
  url?: string;
  remote?: string;
  remoteRef?: string;
  corsProxy?: string;
  headers?: Record<string, string>;
  onProgress?: ProgressCallback;
  onMessage?: MessageCallback;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
  fastForward?: boolean;
  noUpdateBranch?: boolean;
  cache?: object;
}): Promise<void>;

Usage Examples:

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";
import fs from "fs";

// Basic pull from origin/main into current branch
await git.pull({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main"
});

// Pull with authentication and progress tracking
await git.pull({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main",
  onAuth: () => ({
    username: process.env.GIT_USERNAME,
    password: process.env.GIT_TOKEN
  }),
  onProgress: (event) => {
    console.log(`${event.phase}: ${event.loaded}/${event.total}`);
  }
});

// Fast-forward only pull (fail if merge needed)
await git.pull({
  fs,
  http,
  dir: "/path/to/repo",
  remote: "origin",
  ref: "main",
  fastForward: true
});

Add Remote

Adds a new remote repository.

/**
 * Add a remote repository
 * @param args.fs - File system client
 * @param args.dir - Working tree directory path
 * @param args.gitdir - Git directory path
 * @param args.remote - Remote name
 * @param args.url - Remote repository URL
 * @param args.force - Overwrite existing remote
 * @returns Promise resolving when remote is added
 */
function addRemote(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  remote: string;
  url: string;
  force?: boolean;
}): Promise<void>;

Usage Examples:

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

// Add origin remote
await git.addRemote({
  fs,
  dir: "/path/to/repo",
  remote: "origin",
  url: "https://github.com/user/repo.git"
});

// Add upstream remote
await git.addRemote({
  fs,
  dir: "/path/to/repo",
  remote: "upstream",
  url: "https://github.com/original/repo.git"
});

// Force add remote (overwrite existing)
await git.addRemote({
  fs,
  dir: "/path/to/repo",
  remote: "origin",
  url: "https://github.com/user/new-repo.git",
  force: true
});

List Remotes

Lists all configured remotes.

/**
 * List remote repositories
 * @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 remote objects
 */
function listRemotes(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
}): Promise<RemoteDescription[]>;

Usage Example:

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

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

for (const remote of remotes) {
  console.log(`${remote.remote}: ${remote.url}`);
}
// Output:
// origin: https://github.com/user/repo.git
// upstream: https://github.com/original/repo.git

Delete Remote

Removes a remote repository configuration.

/**
 * Delete a remote repository
 * @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 delete
 * @returns Promise resolving when remote is deleted
 */
function deleteRemote(args: {
  fs: FsClient;
  dir?: string;
  gitdir?: string;
  remote: string;
}): Promise<void>;

Usage Example:

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

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

Get Remote Information

Gets detailed information about a remote repository.

/**
 * Get information about a remote repository
 * @param args.http - HTTP client
 * @param args.url - Remote repository URL
 * @param args.corsProxy - CORS proxy URL
 * @param args.headers - Additional HTTP headers
 * @param args.onAuth - Authentication callback
 * @param args.onAuthFailure - Auth failure callback
 * @param args.onAuthSuccess - Auth success callback
 * @returns Promise resolving to remote info
 */
function getRemoteInfo(args: {
  http: HttpClient;
  url: string;
  corsProxy?: string;
  headers?: Record<string, string>;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
}): Promise<GetRemoteInfoResult>;

function getRemoteInfo2(args: {
  http: HttpClient;
  url: string;
  corsProxy?: string;
  headers?: Record<string, string>;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
}): Promise<GetRemoteInfoResult>;

Usage Example:

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";

const info = await git.getRemoteInfo({
  http,
  url: "https://github.com/user/repo.git"
});

console.log("Remote capabilities:", info.capabilities);
console.log("Default branch:", info.HEAD);
console.log("Available refs:", info.refs);

List Server References

Lists all references available on a remote server.

/**
 * List references on remote server
 * @param args.http - HTTP client
 * @param args.url - Remote repository URL
 * @param args.corsProxy - CORS proxy URL
 * @param args.headers - Additional HTTP headers
 * @param args.onAuth - Authentication callback
 * @param args.onAuthFailure - Auth failure callback
 * @param args.onAuthSuccess - Auth success callback
 * @returns Promise resolving to server refs
 */
function listServerRefs(args: {
  http: HttpClient;
  url: string;
  corsProxy?: string;
  headers?: Record<string, string>;
  onAuth?: AuthCallback;
  onAuthFailure?: AuthFailureCallback;
  onAuthSuccess?: AuthSuccessCallback;
}): Promise<ServerRef[]>;

Usage Example:

import git from "isomorphic-git";
import http from "isomorphic-git/http/node";

const refs = await git.listServerRefs({
  http,
  url: "https://github.com/user/repo.git"
});

for (const ref of refs) {
  console.log(`${ref.ref}: ${ref.oid}`);
}
// Output:
// refs/heads/main: abc123...
// refs/heads/develop: def456...
// refs/tags/v1.0.0: ghi789...

Types

interface FetchResult {
  defaultBranch: string;
  fetchHead: string;
  fetchHeadDescription: string;
  headers: Record<string, string>;
  packfile?: string;
  progress?: any[];
}

interface PushResult {
  ok: string[];
  errors: string[];
  headers: Record<string, string>;
}

interface RemoteDescription {
  remote: string;
  url: string;
}

interface GetRemoteInfoResult {
  capabilities: string[];
  HEAD: string;
  refs: Record<string, string>;
}

interface ServerRef {
  ref: string;
  oid: string;
  target?: string;
  peeled?: string;
}

interface AuthResult {
  username?: string;
  password?: string;
  token?: string;
  oauth2format?: "github" | "bitbucket";
  headers?: Record<string, string>;
  cancel?: boolean;
}

interface AuthOptions {
  headers: Record<string, string>;
}

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