steps/git

Low-level Git operations for factory-owned steps. Workflow code normally uses the generated #jigs/steps wrappers.

Inspect changes before publishing them. pushApprovedChange requires the reviewed commit to remain HEAD and the worktree to be clean, including on retries.

Inspect changes

readBranchState()

function readBranchState(worktree, baseSha): Promise<BranchState>;

Inspect branch readiness, counting commits since the worktree's base unless overridden.

Parameters

Parameter	Type	Default value
worktree	Worktree	undefined
baseSha	string	worktree.baseSha

Returns

Promise<BranchState>

---

readChange()

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

Describe committed changes from the worktree's base to HEAD, or supply another base ref.

Parameters

Parameter	Type	Default value
worktree	Worktree	undefined
base	string	worktree.baseSha

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(
   worktree, 
   base, 
   head, 
paths): Promise<ChangePatch>;

Read patches for selected literal paths between two commits.

Parameters

Parameter	Type
worktree	Worktree
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(worktree, baseSha): Promise<string>;

Read a raw patch from the merge base of baseSha and HEAD, truncating after 200,000 characters. Defaults to the worktree's base commit.

Parameters

Parameter	Type	Default value
worktree	Worktree	undefined
baseSha	string	worktree.baseSha

Returns

Promise<string>

Publish changes

pushApprovedChange()

function pushApprovedChange(worktree, 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
worktree	Worktree
approvedCommit	string

Returns

Promise<{ headSha: string; }>

---

pushBranch()

function pushBranch(worktree): Promise<{
  headSha: string;
}>;

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

Parameters

Parameter	Type
worktree	Worktree

Returns

Promise<{ headSha: string; }>