> ## 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.

# getBranchDiff()

> Get the diff between a branch and its base.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // Compare feature branch to main
  const diff = await repo.getBranchDiff({
    branch: 'feature/new-auth',
    base: 'main', // optional, defaults to default branch
  });

  console.log(`Changed files: ${diff.stats.files}`);
  console.log(`+${diff.stats.additions} -${diff.stats.deletions}`);

  diff.files.forEach((file) => {
    if (file.state === 'renamed') {
      console.log(`Renamed: ${file.oldPath} -> ${file.path} (${file.rawState})`);
    }
  });

  // Filter to specific files
  const filteredDiff = await repo.getBranchDiff({
    branch: 'feature/new-auth',
    paths: ['src/auth.ts', 'src/utils/token.ts'],
  });
  ```

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  branch_diff = await repo.get_branch_diff(
      branch="feature/new-auth",
      base="main",  # optional, defaults to main
  )
  print(branch_diff["stats"])
  print(branch_diff["files"])
  for file in branch_diff["files"]:
      if file["state"] == "renamed":
          print(f"Renamed: {file['oldPath']} -> {file['path']} ({file['rawState']})")

  # Filter to specific files
  filtered_diff = await repo.get_branch_diff(
      branch="feature/new-auth",
      paths=["src/auth.py", "src/utils/token.py"],
  )
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // Compare a branch to main
  diff, err := repo.GetBranchDiff(context.Background(), storage.GetBranchDiffOptions{
  	Branch: "feature/new-auth",
  	Base:   "main",
  })
  fmt.Printf("Changed files: %d", diff.Stats.Files)

  // Filter to specific files
  filtered, err := repo.GetBranchDiff(context.Background(), storage.GetBranchDiffOptions{
  	Branch: "feature/new-auth",
  	Paths:  []string{"src/auth.go", "src/utils/token.go"},
  })
  ```
</CodeGroup>

## Options

<ParamField path="branch" type="string" required>
  The branch name to get the diff for
</ParamField>

<ParamField path="base" type="string">
  Base branch to compare against (defaults to repository's default branch)
</ParamField>

<ParamField path="ephemeral" type="string">
  When `true`, resolves the branch under the ephemeral namespace
</ParamField>

<ParamField path="ephemeralBase" type="string">
  When `true`, resolves the base branch under the ephemeral namespace
</ParamField>

<ParamField path="paths" type="string">
  Array of file paths to filter the diff. When provided, only returns diffs for the specified files
  and bypasses size/type filtering
</ParamField>

## Response

<ResponseField name="stats" type="object">
  Summary with `files`, `additions`, `deletions`, and `changes`
</ResponseField>

<ResponseField name="files" type="array">
  List of changed files with `path`, `oldPath`, `state`, `rawState`, and diff content
</ResponseField>

## Notes

* For renamed files, `path` is the new location and `oldPath` is the previous location
* `state` is normalized to `renamed`, while `rawState` preserves Git's original rename code (for
  example `R054`, where `054` is the similarity score)