---
url: https://salimhamed.github.io/jigs/api/steps/git.md
---
# 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()

```ts
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()

```ts
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()

```ts
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()

```ts
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()

```ts
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`](../jigs.md#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()

```ts
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`](../jigs.md#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()

```ts
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`>