WorktreeRepo

Repository with working directory

Provides type-safe wrappers for Git commands that operate on repositories with a working tree. Each method corresponds to a specific Git CLI command or subcommand.

Extends

RepoBase

Properties

branch

branch: BranchOperations

Defined in: src/core/repo.ts:3233

Git branch operations

Wraps: git branch * commands

config

config: ConfigOperations

Defined in: src/core/repo.ts:3566

Git config operations (repository-level)

Wraps: git config (without —global)

lfs

lfs: LfsOperations

Defined in: src/core/repo.ts:3190

Git LFS operations

Wraps: git lfs * commands

lfsExtra

lfsExtra: LfsExtraOperations

Defined in: src/core/repo.ts:3197

Git LFS extra operations (inspired by fs-extra)

Additional utilities for advanced LFS patterns like 2-phase commit/fetch.

remote

remote: RemoteOperations

Defined in: src/core/repo.ts:3559

Git remote operations

Wraps: git remote * commands

stash

stash: StashOperations

Defined in: src/core/repo.ts:3352

Git stash operations

Wraps: git stash * commands

submodule

submodule: SubmoduleOperations

Defined in: src/core/repo.ts:3552

Git submodule operations

Wraps: git submodule * commands

tag

tag: TagOperations

Defined in: src/core/repo.ts:3372

Git tag operations

Wraps: git tag * commands

workdir

readonly workdir: string

Defined in: src/core/repo.ts:3129

Path to the working directory

worktree

worktree: WorktreeOperations

Defined in: src/core/repo.ts:3204

Git worktree operations

Wraps: git worktree * commands

Methods

add()

add(paths, opts?): Promise<void>

Defined in: src/core/repo.ts:3226

Add files to the index

Wraps: git add

Parameters

paths

string | string[]

opts?

AddOpts & ExecOpts

Returns

Promise<void>

Example

await repo.add(['file1.txt', 'file2.txt']);
await repo.add('.', { all: true });

checkout()

Call Signature

checkout(target, opts?): Promise<void>

Defined in: src/core/repo.ts:3247

Checkout a branch, tag, or commit (branch switching mode)

Wraps: git checkout <branch>

Parameters

target

string

opts?

CheckoutBranchOpts & ExecOpts

Returns

Promise<void>

Example

await repo.checkout('main');
await repo.checkout('feature', { createBranch: true });
await repo.checkout('feature', { createBranch: true, startPoint: 'origin/main' });

Call Signature

checkout(paths, opts?): Promise<void>

Defined in: src/core/repo.ts:3269

Checkout specific files from a tree-ish (pathspec mode)

Wraps: git checkout [<tree-ish>] -- <pathspec>...

Parameters

paths

string[]

opts?

CheckoutPathOpts & ExecOpts

Returns

Promise<void>

Example

// Restore file from index (discard working tree changes)
await repo.checkout(['file.txt']);

// Restore file from HEAD
await repo.checkout(['file.txt'], { source: 'HEAD' });

// Restore file from specific commit
await repo.checkout(['src/'], { source: 'abc123' });

// Resolve conflict with ours/theirs
await repo.checkout(['conflicted.txt'], { ours: true });

cherryPick()

cherryPick(commits, opts?): Promise<void>

Defined in: src/core/repo.ts:3389

Apply changes from existing commits

Wraps: git cherry-pick

Parameters

commits

string | string[]

opts?

CherryPickOpts & ExecOpts

Returns

Promise<void>

Example

await repo.cherryPick('abc123');
await repo.cherryPick(['abc123', 'def456']);

clean()

clean(opts?): Promise<string[]>

Defined in: src/core/repo.ts:3401

Remove untracked files from the working tree

Wraps: git clean

Parameters

opts?

CleanOpts & ExecOpts

Returns

Promise<string[]>

Example

const removed = await repo.clean({ force: true, directories: true });

commit()

commit(opts?): Promise<CommitResult>

Defined in: src/core/repo.ts:3282

Create a commit

Wraps: git commit

Parameters

opts?

CommitOpts & ExecOpts

Returns

Promise<CommitResult>

Example

const result = await repo.commit({ message: 'feat: add new feature' });
console.log(result.hash);

diff()

diff(target?, opts?): Promise<DiffResult>

Defined in: src/core/repo.ts:3295

Show changes between commits, commit and working tree, etc.

Wraps: git diff

Parameters

target?

string

opts?

DiffOpts & ExecOpts

Returns

Promise<DiffResult>

Example

const diff = await repo.diff('HEAD~1');
const staged = await repo.diff({ staged: true });

fetch()

fetch(opts?): Promise<void>

Defined in: src/core/repo.ts:3171

Fetch from remote

Wraps: git fetch

Parameters

opts?

FetchOpts & ExecOpts

Returns

Promise<void>

Example

await repo.fetch({ remote: 'origin', prune: true });

isBare()

isBare(): Promise<boolean>

Defined in: src/core/repo.ts:57

Check if this repository is a bare repository (no working directory)

Wraps: git rev-parse --is-bare-repository

This is a runtime check that queries git to determine the repository type. Note: TypeScript cannot automatically narrow the type based on this check since it returns Promise<boolean>. Use type assertions after checking.

Returns

Promise<boolean>

Example

const repo = await git.openRaw('/path/to/repo');
if (await repo.isBare()) {
  // Use type assertion to access BareRepo methods
  await (repo as BareRepo).fetch({ remote: 'origin' });
}

Inherited from

RepoBase.isBare

isWorktree()

isWorktree(): Promise<boolean>

Defined in: src/core/repo.ts:37

Check if this repository is a worktree repository (has working directory)

Wraps: git rev-parse --is-inside-work-tree

Returns

Promise<boolean>

Example

const repo = await git.openRaw('/path/to/repo');
if (await repo.isWorktree()) {
  // Use type assertion to access WorktreeRepo methods
  const status = await (repo as WorktreeRepo).status();
}

Inherited from

RepoBase.isWorktree

log()

log(opts?): Promise<Commit[]>

Defined in: src/core/repo.ts:3159

Get commit log

Wraps: git log

Parameters

opts?

LogOpts & ExecOpts

Returns

Promise<Commit[]>

Example

const commits = await repo.log({ maxCount: 10 });

lsRemote()

lsRemote(remote, opts?): Promise<RepoLsRemoteResult>

Defined in: src/core/repo.ts:79

List references in a remote repository

Wraps: git ls-remote <remote> [refs...]

Unlike the global git.lsRemote(url), this method operates in the context of a repository and accepts a remote name (e.g., ‘origin’) instead of a URL.

Parameters

remote

string

opts?

RepoLsRemoteOpts & ExecOpts

Returns

Promise<RepoLsRemoteResult>

Example

// List all refs from origin
const result = await repo.lsRemote('origin');

// List specific branch
const result = await repo.lsRemote('origin', { refs: ['main'] });

// List only tags
const result = await repo.lsRemote('origin', { tags: true });

Inherited from

RepoBase.lsRemote

lsTree()

lsTree(treeish, opts?): Promise<LsTreeEntry[]>

Defined in: src/core/repo.ts:103

List contents of a tree object

Wraps: git ls-tree <tree-ish> [<path>...]

Lists the contents of a given tree object (commit, tag, or tree hash).

Parameters

treeish

string

opts?

LsTreeOpts & ExecOpts

Returns

Promise<LsTreeEntry[]>

Example

// List all files in HEAD
const entries = await repo.lsTree('HEAD');

// List files recursively with names only
const names = await repo.lsTree('HEAD', { recursive: true, nameOnly: true });

// List files in a specific directory
const entries = await repo.lsTree('main', { paths: ['src/'] });

// Get file sizes
const entries = await repo.lsTree('HEAD', { long: true });

Inherited from

RepoBase.lsTree

merge()

merge(branch, opts?): Promise<MergeResult>

Defined in: src/core/repo.ts:3307

Merge branches

Wraps: git merge

Parameters

branch

string

opts?

MergeOpts & ExecOpts

Returns

Promise<MergeResult>

Example

const result = await repo.merge('feature-branch');

mv()

mv(source, destination, opts?): Promise<void>

Defined in: src/core/repo.ts:3413

Move or rename files

Wraps: git mv

Parameters

source

string

destination

string

opts?

MvOpts & ExecOpts

Returns

Promise<void>

Example

await repo.mv('old-name.txt', 'new-name.txt');

pull()

pull(opts?): Promise<void>

Defined in: src/core/repo.ts:3319

Pull from remote (fetch + merge/rebase)

Wraps: git pull

Parameters

opts?

PullOpts & ExecOpts

Returns

Promise<void>

Example

await repo.pull({ remote: 'origin', rebase: true });

push()

push(opts?): Promise<void>

Defined in: src/core/repo.ts:3183

Push to remote

Wraps: git push

Parameters

opts?

PushOpts & ExecOpts

Returns

Promise<void>

Example

await repo.push({ remote: 'origin', refspec: 'main' });

raw()

raw(argv, opts?): Promise<RawResult>

Defined in: src/core/repo.ts:17

Execute a raw git command in this repository context

Wraps: git <argv...>

Parameters

argv

string[]

rebase()

rebase(opts?): Promise<void>

Defined in: src/core/repo.ts:3426

Reapply commits on top of another base

Wraps: git rebase

Parameters

opts?

RebaseOpts & ExecOpts

Returns

Promise<void>

Example

await repo.rebase({ onto: 'main' });
await repo.rebase({ abort: true });

reset()

reset(target?, opts?): Promise<void>

Defined in: src/core/repo.ts:3332

Reset current HEAD to the specified state

Wraps: git reset

Parameters

target?

string

opts?

ResetOpts & ExecOpts

Returns

Promise<void>

Example

await repo.reset('HEAD~1', { hard: true });
await repo.reset({ soft: true });

restore()

restore(paths, opts?): Promise<void>

Defined in: src/core/repo.ts:3439

Restore working tree files

Wraps: git restore

Parameters

paths

string | string[]

opts?

RestoreOpts & ExecOpts

Returns

Promise<void>

Example

await repo.restore(['file.txt'], { staged: true });
await repo.restore(['.'], { source: 'HEAD' });

revert()

revert(commits, opts?): Promise<void>

Defined in: src/core/repo.ts:3452

Revert existing commits

Wraps: git revert

Parameters

commits

string | string[]

opts?

RevertOpts & ExecOpts

Returns

Promise<void>

Example

await repo.revert('abc123');
await repo.revert(['abc123', 'def456'], { noCommit: true });

revListCount()

revListCount(ref?, opts?): Promise<number>

Defined in: src/core/repo.ts:3526

Count the number of commits reachable from a ref

Wraps: git rev-list --count

Parameters

ref?

string

opts?

ExecOpts

Returns

Promise<number>

Example

const count = await repo.revListCount('HEAD');
const featureCommits = await repo.revListCount('main..feature');

revParse()

Call Signature

revParse(ref, opts?): Promise<string>

Defined in: src/core/repo.ts:3505

Parse revision specification and return information about the repository

Wraps: git rev-parse

This is a versatile command with multiple use cases based on the options provided:

Resolve ref to SHA:

const sha = await repo.revParse('HEAD');
const parentSha = await repo.revParse('HEAD~1');
const short = await repo.revParse('HEAD', { short: true });
const branch = await repo.revParse('HEAD', { abbrevRef: true });

Query paths:

const gitDir = await repo.revParse({ gitDir: true });
const toplevel = await repo.revParse({ showToplevel: true });

Query repository state:

const isShallow = await repo.revParse({ isShallowRepository: true });
const isBare = await repo.revParse({ isBareRepository: true });

List refs:

const allRefs = await repo.revParse({ all: true });
const branches = await repo.revParse({ branches: true });
const featureBranches = await repo.revParse({ branches: 'feature/*' });

Parameters

ref

string

opts?

RevParseRefOpts & ExecOpts

Returns

Promise<string>

Call Signature

revParse(opts): Promise<string>

Defined in: src/core/repo.ts:3506

Parameters

opts

RevParsePathQuery & RevParsePathOpts & ExecOpts

Returns

Promise<string>

Call Signature

revParse(opts): Promise<boolean>

Defined in: src/core/repo.ts:3507

Parameters

opts

RevParseBooleanQuery & ExecOpts

Returns

Promise<boolean>

Call Signature

revParse(opts): Promise<string[]>

Defined in: src/core/repo.ts:3508

Parameters

opts

RevParseListQuery & ExecOpts

Returns

Promise<string[]>

Call Signature

revParse(opts): Promise<string>

Defined in: src/core/repo.ts:3509

Parameters

opts

object & ExecOpts

Returns

Promise<string>

Call Signature

revParse(opts): Promise<string>

Defined in: src/core/repo.ts:3512

Parameters

opts

object & ExecOpts

Returns

Promise<string>

Call Signature

revParse(opts): Promise<string[]>

Defined in: src/core/repo.ts:3513

Parameters

opts

object & ExecOpts

Returns

Promise<string[]>

rm()

rm(paths, opts?): Promise<void>

Defined in: src/core/repo.ts:3345

Remove files from the working tree and from the index

Wraps: git rm

Parameters

paths

string | string[]

opts?

RmOpts & ExecOpts

Returns

Promise<void>

Example

await repo.rm('file.txt');
await repo.rm('dir/', { recursive: true });

setLfsMode()

setLfsMode(mode): void

Defined in: src/core/repo.ts:3209

Configure LFS mode for this repository

Parameters

mode

LfsMode

Returns

void

show()

show(object, opts?): Promise<string>

Defined in: src/core/repo.ts:3465

Show various types of objects

Wraps: git show

Parameters

object

string

opts?

ShowOpts & ExecOpts

Returns

Promise<string>

Example

const content = await repo.show('HEAD:README.md');
const commitInfo = await repo.show('abc123');

status()

status(opts?): Promise<StatusPorcelain>

Defined in: src/core/repo.ts:3147

Get repository status

Wraps: git status

Parameters

opts?

StatusOpts & ExecOpts

Returns

Promise<StatusPorcelain>

Example

const status = await repo.status();
console.log(status.entries); // Changed files
console.log(status.branch);  // Current branch

switch()

switch(branch, opts?): Promise<void>

Defined in: src/core/repo.ts:3365

Switch branches

Wraps: git switch

Parameters

branch

string

opts?

SwitchOpts & ExecOpts

Returns

Promise<void>

Example

await repo.switch('main');
await repo.switch('new-branch', { create: true });

symbolicRef()

symbolicRef(name, newRef?, opts?): Promise<string | undefined>

Defined in: src/core/repo.ts:3545

Read or modify symbolic refs

Wraps: git symbolic-ref

Without newRef: reads the symbolic ref (e.g., get what HEAD points to) With newRef: sets the symbolic ref to point to newRef

Parameters

name

string

newRef?

string

opts?

ExecOpts

Returns

Promise<string | undefined>

Example

// Read what HEAD points to
const branch = await repo.symbolicRef('HEAD');

// Set HEAD to point to a branch
await repo.symbolicRef('HEAD', 'refs/heads/main');