steps/git

Inspect committed changes and push branches in a Git worktree.

Wrap steps in a factory-owned "use step" file. Never call them directly from a workflow.

Functions

branchContains()

function branchContains(worktreePath, sha): Promise<boolean>;

Whether sha is the worktree's HEAD or one of its ancestors. A commit the worktree has never fetched is not contained.

Parameters

Parameter	Type
worktreePath	string
sha	string

Returns

Promise<boolean>

---

pushApprovedChange()

function pushApprovedChange(
   worktreePath, 
   branch, 
   approvedCommit): Promise<{
  headSha: string;
}>;

Push a reviewed commit only while it is still HEAD and the worktree is clean.

Safe to retry after a successful push. Rejects if HEAD moved or any uncommitted change exists.

Parameters

Parameter	Type
worktreePath	string
branch	string
approvedCommit	string

Returns

Promise<{ headSha: string; }>

---

pushBranch()

function pushBranch(worktreePath, branch): Promise<{
  headSha: string;
}>;

Push the worktree's current HEAD and register a GitHub branch resource when applicable.

Parameters

Parameter	Type
worktreePath	string
branch	string

Returns

Promise<{ headSha: string; }>

---

readBranchState()

function readBranchState(worktreePath, baseSha): Promise<{
  commits: number;
  dirty: boolean;
  headSha: string;
}>;

Inspect the worktree state used to decide whether a branch is ready to push.

Parameters

Parameter	Type
worktreePath	string
baseSha	string

Returns

Promise<{ commits: number; dirty: boolean; headSha: string; }>

---

readChange()

function readChange(worktreePath, base): Promise<ChangeSummary>;

Describe committed changes between a base ref and the worktree's current HEAD.

Parameters

Parameter	Type
worktreePath	string
base	string

Returns

Promise<ChangeSummary>

Remarks

Resolves both endpoints once, compares their trees directly and lists commits reachable only from HEAD. Returns at most 1,000 files and 1,000 commits; truncated reports omitted results.

---

readPatch()

function readPatch(
   worktreePath, 
   base, 
   head, 
paths): Promise<ChangePatch>;

Read patches for selected literal paths between two commits.

Parameters

Parameter	Type
worktreePath	string
base	string
head	string
paths	string[]

Returns

Promise<ChangePatch>

Remarks

Pass the resolved base and head from readChange to inspect that exact change. Paths are deduplicated, empty paths are rejected and all returned patches share a 200,000-character limit.

---

readWorktreeDiff()

function readWorktreeDiff(worktreePath, baseSha): Promise<string>;

Read a raw patch from the merge base of baseSha and HEAD, truncating after 200,000 characters.

Parameters

Parameter	Type
worktreePath	string
baseSha	string

Returns

Promise<string>