> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# createCommitFromDiff()

> Apply a pre-generated Git patch without constructing a builder.

This helper wraps the `/api/repos/{repo_name}/diff-commit` endpoint and is designed for workflows
that already have `git diff --binary` output available.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  const diff = await fs.readFile('dist/generated.patch', 'utf8');

  const result = await repo.createCommitFromDiff({
    targetBranch: 'main',
    expectedHeadSha: currentHeadSha,
    commitMessage: 'Apply generated SDK patch',
    author: { name: 'Diff Bot', email: 'diff@example.com' },
    committer: { name: 'Diff Bot', email: 'diff@example.com' },
    diff,
  });

  console.log(result.commitSha);
  console.log(result.refUpdate.newSha);
  console.log(result.refUpdate.oldSha);
  ```

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  from pathlib import Path

  diff_text = Path("dist/generated.patch").read_text()

  result = await repo.create_commit_from_diff(
      target_branch="main",
      expected_head_sha=current_head_sha,  # optional safety check
      commit_message="Apply generated SDK patch",
      author={"name": "Diff Bot", "email": "diff@example.com"},
      committer={"name": "Diff Bot", "email": "diff@example.com"},
      diff=diff_text,
      base_branch="release",          # optional branch fallback
  )

  print(result["commit_sha"])
  print(result["ref_update"]["new_sha"])
  print(result["ref_update"]["old_sha"])  # All zeroes when ref is created
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // Load a generated patch
  diffFile, err := os.Open("dist/generated.patch")
  defer diffFile.Close()

  // Apply the diff as a commit
  result, err := repo.CreateCommitFromDiff(context.Background(), storage.CommitFromDiffOptions{
  	TargetBranch:    "main",
  	ExpectedHeadSHA: currentHeadSHA,
  	CommitMessage:   "Apply generated SDK patch",
  	Author:          storage.CommitSignature{Name: "Diff Bot", Email: "diff@example.com"},
  	Committer:       &storage.CommitSignature{Name: "Diff Bot", Email: "diff@example.com"},
  	Diff:            diffFile,
  	BaseBranch:      "release",
  })

  fmt.Println(result.CommitSHA)
  fmt.Println(result.RefUpdate.NewSHA)
  fmt.Println(result.RefUpdate.OldSHA)
  ```
</CodeGroup>

`createCommitFromDiff` shares the same branch metadata (`expectedHeadSha`, `baseBranch`,
`ephemeral`, `ephemeralBase`) as `createCommit`. Instead of calling `.addFile()`, pass the patch
contents through the `diff` field. The SDK accepts strings, `Uint8Array`, `ArrayBuffer`, Blob/File
objects, or any iterable/async iterable of byte chunks and handles chunking + base64 encoding. In
Go, the `Diff` field accepts an `io.Reader`.

The gateway applies the patch with `git apply --cached --binary`, so make sure your diff is
compatible with that command. It must include file headers (`diff --git`), mode lines, and hunk
headers. Empty patches and patches that do not apply cleanly result in a `RefUpdateError` with the
mapped status ( `conflict`, `precondition_failed`, etc.) and partial ref update information.

## Options

<ParamField path="targetBranch" type="string" required>
  Branch name that will receive the commit.
</ParamField>

<ParamField path="commitMessage" type="string" required>
  The commit message.
</ParamField>

<ParamField path="author" type="string" required>
  Provide `name` and `email` for the commit author.
</ParamField>

<ParamField path="diff" type="string" required>
  The patch content (string, bytes, async iterable, or `io.Reader` in Go).
</ParamField>

<ParamField path="expectedHeadSha" type="string">
  Commit SHA that must match the remote tip.
</ParamField>

<ParamField path="baseBranch" type="string">
  Branch to seed from if target doesn't exist.
</ParamField>

<ParamField path="ephemeral" type="string">
  Store in the ephemeral namespace.
</ParamField>

<ParamField path="ephemeralBase" type="string">
  Use when the base branch is also ephemeral.
</ParamField>

<ParamField path="committer" type="string">
  Provide `name` and `email`. Defaults to author if omitted.
</ParamField>

<ParamField path="refPolicies" type="object[]">
  Ordered per-ref policy rules (`{ pattern, ops? }`) embedded in the per-call JWT. First match wins. Python: `ref_policies`. Go: `RefPolicies` with type `storage.RefPolicyList`. See the [Branch Protection guide](/docs/guides/branch-protection).
</ParamField>

## Response

<ResponseField name="commitSha" type="string">
  The SHA of the created commit
</ResponseField>

<ResponseField name="treeSha" type="string">
  The SHA of the commit's tree object
</ResponseField>

<ResponseField name="targetBranch" type="string">
  The branch that received the commit
</ResponseField>

<ResponseField name="packBytes" type="number">
  Size of the uploaded pack in bytes
</ResponseField>

<ResponseField name="refUpdate" type="object">
  Contains `branch`, `oldSha`/`old_sha`, and `newSha`/`new_sha`
</ResponseField>