Skip to content
Pando

The branch diff (GitHub's three-dot diff, merge base to head)

Computed in the Worker from Artifacts reads, with no clone: the merge base, a walk of the two trees that skips equal subtrees, the changed blobs only, and a line diff (patience, then bounded Myers between its anchors, as git diff --patience). Exact renames (the same blob moved) show as renamed; there is no similarity rename detection.

max_bytes bounds the bytes of hunk lines returned. Files past the budget keep their entry with patch_omitted: budget. A text file over 8 MiB on either side has patch_omitted: too_large and null counts.

Files changed (patches=1): the answer is a BranchDiff, each file with its own unified patch in git's format (patch, ready for a diff view such as @pierre/diffs' processFile), or null when left out: a binary (a NUL in the first 8,000 bytes), a text file over 8 MiB on either side, or past 2 MiB of patches in all. At most 1,000 files are listed (too_many_files, with files_total). Main and the head come from Pando's stored heads; the answer is kept by (main, head), which never changes, so a repeat costs no Artifacts read, and ETag is the two shas (a repeat with If-None-Match is a 304). format, hunks, max_bytes and paths do not apply.

Files changed, streamed (patches=1&stream=1, the web's branch page, for a branch of any size): application/x-ndjson, one BranchDiffLine a line, each sent as soon as it is known: start (the ends, the merge base, files_total, too_many_files), then one file per changed file (a DiffFile with its patch) in a file tree's order (folders before files at each level, by name), then end (stats, truncated); error if the diff fails after its start. At most 5,000 files, and 32 MiB of patches in all. Each pair of blobs diffed is kept in R2, so the next head of a branch reads only the pairs a push changed; the whole answer is kept by (main, head) once streamed, and streamed from there after with the same ETag and 304. An answer being computed has no ETag (Cache-Control: no-store): it may stop part way, with an error line, and the next request goes on from the pairs already kept.

GET
https://app.gitpando.com/v1/monorepos/{owner}/{monorepo}/repos/{repo}/branches/{branch}/diff
View as Markdown

Authorisation

  • credentialoptionalHTTP
  • sessionoptionalAPI key in cookie

Path parameters

  • ownerstringrequired

    The monorepo's owner, a namespace (a person's login or an organization). Matched without case.

    pattern: ^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$
  • monorepostringrequired

    The monorepo's name within its owner (or an old name). Matched without case.

    pattern: ^[a-z0-9](?:[a-z0-9._]|-(?!-)){0,38}$
  • repostringrequired

    The repo's name (projects-web).

  • branchstringrequired

    The branch name, / encoded as %2F.

Query parameters

  • formatoptionaljsonorpatch
    Default: "json"
  • hunksoptional0or1

    1 to include per-file hunks in JSON.

    Default: "0"
  • max_bytesoptionalinteger

    Budget for hunk bytes. Default 1048576, maximum 8388608.

    minimum: 0
  • pathsoptionalstring

    Path prefixes, comma-separated or repeated (paths=src/auth/&paths=README.md).

  • patchesoptional0or1

    1: Files changed, a BranchDiff (see above).

    Default: "0"
  • streamoptional0or1

    1 with patches=1: Files changed as NDJSON, a BranchDiffLine a line (see above).

    Default: "0"

Returns

200

JSON (a BranchDiff with patches=1), or text/x-patch for format=patch: a unified diff with diff --git headers, ready for git apply or plannotator review --patch-file -. In patch form, files past the budget are left out and the response carries X-Pando-Diff-Omitted: <count>.

JSON

One of the following:

  • Diff
    View Diff schema →
    7 properties
    • base_branchstringrequired

      The default branch.

    • basestringrequired

      The default branch's head.

    • headstringrequired

      The branch head.

    • merge_basestringrequired

      Where the diff starts (three-dot).

    • truncatedbooleanrequired

      True when any file has patch_omitted: budget.

    • filesarray ofobjectrequired
      12 properties
      • pathstringrequired
      • statusaddedormodifiedordeletedorrenamedrequired
      • binarybooleanrequired
      • old_pathoptionalstring

        Only for renamed.

      • old_shaoptionalstring | null
      • new_shaoptionalstring | null
      • old_modeoptionalstring | null
      • new_modeoptionalstring | null
      • additionsoptionalinteger | null
      • deletionsoptionalinteger | null
      • hunksoptionalarray ofobject

        Only with hunks=1.

        5 properties
        • old_startintegerrequired
        • old_linesintegerrequired
        • new_startintegerrequired
        • new_linesintegerrequired
        • linesarray ofstringrequired

          Each line starts with +, -, , or \ (no newline at end of file).

      • patch_omittedoptionalbinaryortoo_largeorbudget
    • statsoptionalobject
      3 properties
      • filesoptionalinteger
      • additionsoptionalinteger
      • deletionsoptionalinteger
  • BranchDiff
    View BranchDiff schema →
    9 properties
    • base_branchstringrequired
    • basestringrequired

      Main's head the diff was taken against; for a branch Pando merged at this head, main just before that merge (the merge commit's first parent), so a merged branch keeps its changes.

    • headstringrequired

      The branch's head.

    • merge_basestringrequired
    • truncatedbooleanrequired

      Some patches were left out past 2 MiB in all (patch_omitted: budget).

    • too_many_filesbooleanrequired

      More than 1

    • files_totalintegerrequired

      Every changed file

    • statsobjectrequired

      The listed files.

      3 properties
      • filesoptionalinteger
      • additionsoptionalinteger
      • deletionsoptionalinteger
    • filesarray ofunknownrequired
      13 properties
      • pathstringrequired
      • statusaddedormodifiedordeletedorrenamedrequired
      • binarybooleanrequired
      • patchstring | nullrequired

        This file's unified patch in git's format; null when patch_omitted is set.

      • old_pathoptionalstring

        Only for renamed.

      • old_shaoptionalstring | null
      • new_shaoptionalstring | null
      • old_modeoptionalstring | null
      • new_modeoptionalstring | null
      • additionsoptionalinteger | null
      • deletionsoptionalinteger | null
      • hunksoptionalarray ofobject

        Only with hunks=1.

        5 properties
        • old_startintegerrequired
        • old_linesintegerrequired
        • new_startintegerrequired
        • new_linesintegerrequired
        • linesarray ofstringrequired

          Each line starts with +, -, , or \ (no newline at end of file).

      • patch_omittedoptionalbinaryortoo_largeorbudget
X-PATCH
string
X-NDJSON

One of the following:

  • object
  • object
  • object
  • object
{
  "type": "start",
  "base_branch": "string",
  "base": "string",
  "head": "string",
  "merge_base": "string",
  "files_total": 0,
  "too_many_files": true
}

304

patches=1 with If-None-Match naming this (main, head).

404

An error

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
    • messagestringrequired
    • pathsoptionalarray ofstring
    • checksoptionalobject

      GitHub's combined status, plus the required contexts and which are missing.

      6 properties
      • shastring | nullrequired
      • statesuccessorpendingorfailureorerrorormissingorunknownrequired

        success when the merge gate passes; missing when a required context has not reported; unknown while the required checks are (an unforced merge is refused).

      • requiredarray | nullrequired

        Null while unknown.

      • checks_unknownstring | nullrequired

        Why the required checks are unknown, in plain words: "Pando couldn't read this monorepo's required checks; try again", or "pando.toml line 3: expected comma or end of structure; fix it on main, or merge with force". Null otherwise.

      • statusesarray ofobjectrequired

        The latest status per context.

        8 properties
        • shastringrequired
        • contextstringrequired
        • statependingorsuccessorfailureorerrorrequired
        • created_atstringrequired
          format: date-time
        • target_urloptionalstring | null
        • descriptionoptionalstring | null
        • creatoroptionalstring

          The member who posted it (a login); app:<slug> for a status posted with a status token or by a CI integration; hook:<hook id> for a status token from a web hook with no app.

        • appoptionalstring | null

          The CI service that reported it (buildkite, github-actions, ...), stamped by Pando from a status token or a CI integration, never from the body or target_url. Null when a member posted it with their own credential. The web shows the service's mark for a slug it knows.

      • missingoptionalarray ofstring

409

no_merge_base: the branch shares no history with the default branch.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
    • messagestringrequired
    • pathsoptionalarray ofstring
    • checksoptionalobject

      GitHub's combined status, plus the required contexts and which are missing.

      6 properties
      • shastring | nullrequired
      • statesuccessorpendingorfailureorerrorormissingorunknownrequired

        success when the merge gate passes; missing when a required context has not reported; unknown while the required checks are (an unforced merge is refused).

      • requiredarray | nullrequired

        Null while unknown.

      • checks_unknownstring | nullrequired

        Why the required checks are unknown, in plain words: "Pando couldn't read this monorepo's required checks; try again", or "pando.toml line 3: expected comma or end of structure; fix it on main, or merge with force". Null otherwise.

      • statusesarray ofobjectrequired

        The latest status per context.

        8 properties
        • shastringrequired
        • contextstringrequired
        • statependingorsuccessorfailureorerrorrequired
        • created_atstringrequired
          format: date-time
        • target_urloptionalstring | null
        • descriptionoptionalstring | null
        • creatoroptionalstring

          The member who posted it (a login); app:<slug> for a status posted with a status token or by a CI integration; hook:<hook id> for a status token from a web hook with no app.

        • appoptionalstring | null

          The CI service that reported it (buildkite, github-actions, ...), stamped by Pando from a status token or a CI integration, never from the body or target_url. Null when a member posted it with their own credential. The web shows the service's mark for a slug it knows.

      • missingoptionalarray ofstring
Navigation

Type to search…

↑↓ navigate↵ selectEsc close