Skip to main content
Compares a feature branch to its base so you can review every change before merging.
GET /api/v1/repos/branches/diff?branch=BRANCH_NAME&base=BASE_BRANCH&ephemeral=true&ephemeral_base=false&path=src/main.go&path=README.md
Authorization: Bearer YOUR_JWT_TOKEN

Parameters

ParameterTypeDescription
branchRequiredThe branch name to get the diff for
baseOptionalBase branch to compare against (defaults to repository’s default branch)
ephemeralOptionalWhen true, resolves the branch ref under refs/namespaces/ephemeral/refs/heads/<branch>
ephemeral_baseOptionalWhen true, resolves the base ref under refs/namespaces/ephemeral/refs/heads/<base>
pathOptionalFile path(s) to filter the diff. Can be specified multiple times to include multiple files. When provided, only returns diffs for the specified files and bypasses size/type filtering

JWT Requirements

  • The JWT must include the repository in the repo claim
  • Requires git:read scope

Response

{
  "branch": "feature/new-feature",
  "base": "main",
  "stats": {
    "files": 5,
    "additions": 120,
    "deletions": 30,
    "changes": 150
  },
  "files": [
    {
      "path": "src/feature.go",
      "state": "A",
      "old_path": "",
      "bytes": 2048,
      "is_eof": true,
      "raw": "diff --git a/src/feature.go b/src/feature.go\nnew file mode 100644\nindex 0000000..abc123\n--- /dev/null\n+++ b/src/feature.go\n@@ -0,0 +1,50 @@\n+package main\n+\n+func NewFeature() {\n+    // Implementation\n+}\n"
    },
    {
      "path": "src/main.go",
      "state": "M",
      "old_path": "",
      "bytes": 1024,
      "is_eof": true,
      "raw": "diff --git a/src/main.go b/src/main.go\nindex abc123..def456 100644\n--- a/src/main.go\n+++ b/src/main.go\n@@ -10,6 +10,8 @@\n+    feature := NewFeature()\n+    feature.Run()\n"
    }
  ],
  "filtered_files": [
    {
      "path": "go.sum",
      "state": "M",
      "old_path": "",
      "bytes": 50000,
      "is_eof": true
    }
  ]
}

Notes

  • Shows all changes in the branch compared to the base branch
  • If base is not specified, compares against the repository’s default branch (usually “main”)
  • Uses three-dot diff notation internally (base…branch) to show changes since branch diverged
  • Large files and binary files are included in filtered_files without diff content
  • When path is specified, size and type filtering is bypassed—requested files are always returned with full diff content
  • Useful for reviewing all changes in a feature branch before merging
  • For more about ephemeral branches, see the Ephemeral branches guide

Error Responses

StatusDescription
404 Not FoundBranch or base branch doesn’t exist
401 UnauthorizedInvalid JWT or missing git:read scope
400 Bad RequestMissing branch parameter or invalid ephemeral/ephemeral_base value