Git Operations

Key Interfaces

TypeGit

Pre-configured convenience class for each runtime:

import { TypeGit } from 'type-git/node';

const git = new TypeGit();
// Automatically configured with Node.js adapters

When to use: Most applications. Simplest way to get started.

Git

The core interface for repository-agnostic operations:

interface Git {
  open(path: string): Promise<WorktreeRepo | BareRepo>;
  clone(url: string, path: string, opts?: CloneOpts): Promise<WorktreeRepo | BareRepo>;
  init(path: string, opts?: InitOpts): Promise<WorktreeRepo | BareRepo>;
  lsRemote(url: string, opts?: LsRemoteOpts): Promise<LsRemoteResult>;
  version(): Promise<string>;
  raw(argv: string[]): Promise<RawResult>;
}

When to use: When you need the underlying interface, or when using createGit() with custom adapters.

WorktreeRepo

Standard repository with working directory:

interface WorktreeRepo {
  readonly workdir: string;

  // Core operations
  status(opts?: StatusOpts): Promise<StatusPorcelain>;
  log(opts?: LogOpts): Promise<Commit[]>;
  add(paths: string[], opts?: AddOpts): Promise<void>;
  commit(opts?: CommitOpts): Promise<CommitResult>;

  // Remote operations
  fetch(opts?: FetchOpts): Promise<void>;
  push(opts?: PushOpts): Promise<void>;
  pull(opts?: PullOpts): Promise<void>;

  // Nested operations
  branch: BranchOperations;
  stash: StashOperations;
  tag: TagOperations;
  lfs: LfsOperations;
  lfsExtra: LfsExtraOperations;
  worktree: WorktreeOperations;

  // Raw access
  raw(argv: string[]): Promise<RawResult>;
}

BareRepo

Repository without working directory (mirrors, servers):

interface BareRepo {
  readonly gitDir: string;

  fetch(opts?: FetchOpts): Promise<void>;
  push(opts?: PushOpts): Promise<void>;
  raw(argv: string[]): Promise<RawResult>;
}

Note: Bare repos have limited operations since there’s no working directory.

CliRunner

Low-level command execution engine:

class CliRunner {
  constructor(adapters: RuntimeAdapters, options?: CliRunnerOptions);

  run(context: ExecutionContext, args: string[], opts?: ExecOpts): Promise<RawResult>;
  runOrThrow(context: ExecutionContext, args: string[], opts?: ExecOpts): Promise<RawResult>;
}

When to use: Building custom git wrappers or extending type-git.

GitError

Structured error with semantic information:

class GitError extends Error {
  readonly kind: 'NonZeroExit' | 'Aborted' | 'SpawnFailed';
  readonly category: GitErrorCategory;
  readonly exitCode: number;
  readonly stdout: string;
  readonly stderr: string;
  readonly argv: string[];
}

Nested Operations

Several operations are grouped under namespaced properties:

branch

await repo.branch.list();                    // List branches
await repo.branch.current();                 // Get current branch name
await repo.branch.create('feature-x');       // Create branch
await repo.branch.delete('old-branch');      // Delete branch
await repo.branch.rename('old', 'new');      // Rename branch

stash

await repo.stash.list();                     // List stash entries
await repo.stash.push({ message: 'WIP' });   // Stash changes
await repo.stash.pop();                      // Pop latest stash
await repo.stash.apply({ index: 1 });        // Apply specific stash
await repo.stash.drop(0);                    // Drop stash entry
await repo.stash.clear();                    // Clear all stashes

tag

await repo.tag.list();                       // List tags
await repo.tag.create('v1.0.0');             // Create lightweight tag
await repo.tag.create('v1.0.0', {            // Create annotated tag
  message: 'Release 1.0'
});
await repo.tag.delete('old-tag');            // Delete tag
await repo.tag.show('v1.0.0');               // Get tag info

lfs / lfsExtra

// Basic LFS
await repo.lfs.pull();
await repo.lfs.push();
await repo.lfs.status();

// Advanced LFS (2-phase patterns)
await repo.lfsExtra.preUpload();
await repo.lfsExtra.preDownload({ ref: 'main' });

worktree

await repo.worktree.list();                  // List worktrees
await repo.worktree.add('./wt', {            // Add worktree
  branch: 'feature-x'
});
await repo.worktree.remove('./wt');          // Remove worktree
await repo.worktree.lock('./wt');            // Lock worktree
await repo.worktree.unlock('./wt');          // Unlock worktree