Diffs and comparisons

Overview

See exactly what changed. You can read what a single commit introduced, what a merge request would land, what separates any two branches, every file a change touches in one response, and — for a file the diff folded away or one too large to send whole — that one file's full patch or a window of its lines. Every answer is computed from git at the moment you ask, so a diff is the repository as it stands rather than a stored summary that can quietly fall out of date.

All eight reads are read-only and share one token scope, which makes this the surface to point a review tool, a bot or a CI script at.

Before you start

The last four take their SHAs from whichever diff you are already reading, and it matters which pair you copy. A commit diff and a merge request diff carry base_sha and head_sha at the top level. A comparison and a stack diff nest theirs under diff, and it is diff.base_sha and diff.head_sha you want — a comparison's own top-level base_sha is the base branch's tip, which is a different commit and gives you a different diff. Passing the right pair back is what keeps everything you read afterwards — more pages, the file list, a file you expand — consistent with the change you were looking at, even if somebody pushes to the branch while you read.

How it works

What each diff is taken against

The merge request, comparison and stack reads are three-dot: they start where the two branches last agreed, not at the target's current tip. Each one's base_sha is that starting point, so reading the same diff again by its commit pair gives the same answer.

That is the difference between a review that shows your four commits and one that also shows the fifteen that landed on the default branch while you were working. It also means a diff never grows because somebody else merged something: only a push to your own branch changes it.

The cost of three-dot is the one thing it hides — work that is on the base and not on your branch. A comparison reports that separately as behind, and a merge request reports it in its merge check.

Stats always, patches on request

Every batch read returns two things: aggregate counts for the whole change, and one alphabetically ordered page of files. Patch text is off by default, because the counts are what most callers want and the patch bodies are nearly all of the bytes. Turn patches on with include_patch, and move through the file list with page and limit.

The numbers in stats describe the entire change, not the page you are holding — so a page of 20 files can sit under a files_changed of 300 without either being wrong. total_files counts the same set, and has_more says whether another page exists. Asking for a page past the end is not an error: it returns an empty files list. On a comparison and on a stack diff every one of those lives under diff; the divergence counts and the commit preview belong to the comparison itself.

The whole file list in one read

Paging is for patches. When what you want is the list — every file the change touches, with its status and its counts, to draw a file tree or to find one file among thousands — ask for the file list instead. It returns every changed file in path order in one response, with no patch text, and the same whole-change stats as a page.

The list is cheap because it is the part of a diff that was already computed: the counts come from the same single pass that serves every page. A few thousand files is a few hundred kilobytes of JSON and far less on the wire, where it is compressed. So the pattern for a large change is one read for the list, then patches only for the files the reader actually reaches — rather than paging through every file to discover what is there.

A renamed file carries its old_path in the list. Pass it along when you open that file on its own, so its diff reads as the rename it is.

Folded files and files that are simply too big

Two different things can leave a file without patch text, and they want different responses from you.

Your repository decides what counts as generated. A linguist-generated attribute in .gitattributes, read at the head of the change, is authoritative in both directions: it marks files the built-in list would miss, and linguist-generated=false forces a lock file to be shown in full. Only paths the attribute says nothing about fall back to the built-in list — dependency lock files by name (Cargo.lock, package-lock.json, yarn.lock, go.sum, Gemfile.lock, poetry.lock and their siblings) and .min.js, .min.css, .map and .snap by suffix. The attribute is read only on a request that is folding patches; a stats-only read reports generated from the built-in list alone.

Folding never costs you accuracy: it is decided from the file's path and its changed-line counts before any patch is produced, so a folded file's additions and deletions are the real ones. Send collapse=false when you want every patch on the page regardless.

Diffs outlive branches

A merge request carries the two branch tips it was opened at, and refreshes them when it merges. Once it has merged, or once its source branch is deleted, its diff is taken between those recorded commits rather than between live branch names — so a merged merge request keeps showing exactly what landed, long after the branch is gone.

A merged merge request's commits stay reachable from the branch it merged into, so that diff keeps working indefinitely. The one case that decays is a closed merge request whose source branch was deleted: nothing on any branch reaches those commits any more, and repository housekeeping eventually reclaims them. Compare the two branches instead, while both still exist.

While a merge request is open and its source branch still exists, the diff is taken from live branch tips — so it follows every push to the source branch.

Re-reading is nearly free

Every read returns an ETag. Send it back on the next request as If-None-Match and an unchanged answer comes back as 304 Not Modified with no body at all. The validator covers the resolved commit pair and the options you sent, so switching include_patch or turning a page gets you fresh content rather than a stale 304. The check runs after the access check, so a 304 never tells an unauthorized caller that something exists.

How to

Read what a commit changed

A commit diff is taken against the commit's first parent, so for a merge commit you get what the merge introduced relative to its first side. Start with the counts, then ask for patches once you know how big the change is.

If the response comes back with truncated: true, the commit touched more files than one diff can carry — see Limits.

Read what a merge request changes

This is the review view: only what the source branch introduces, measured from the point it diverged from its target.

For a merge request that is part of a stack, this shows only that one merge request's own layer. Use the stack diff below for everything underneath it as well.

Compare two branches

A comparison answers two questions at once: how far the branches have diverged (ahead and behind), and what the head branch introduces. Both base and head are required and both must be branch names.

Direction matters. base is where you would merge to and head is where the work is, exactly as in a merge request — so comparing main against feature shows the feature's work, and the other way round shows nothing but what main has moved on by.

The commit list in the response is a preview rather than the whole history. When commits_truncated is true, ahead and total_commits still hold the real number — only the list was cut. There is no cursor for the rest of it: read the merge request's own commit listing if a merge request exists for this pair — that one is a merge request read, so a token needs merge_request:read as well — or run git log base..head in a clone.

Read a whole stack as one change

When merge requests are stacked, each one targets the branch below it, so each one's own diff shows only its layer. A stack diff rolls up the whole chain from the stack's base branch to the merge request you anchor on — exactly the change that merging the chain would apply.

member_mr_ids names the merge requests that were rolled in, base-first with the anchor last, so you can tell at a glance how much of the chain you are reading. The chain above the anchor is deliberately excluded: it branches, and there is no single cumulative answer for a tree.

Expand a file the diff folded away

The single-file read is the other half of folding. Give it the commit pair the batch diff was built from — base_sha and head_sha on a commit or merge request diff, diff.base_sha and diff.head_sha on a comparison or a stack diff — plus the file's path exactly as the diff spelled it. It returns that one file force-expanded: folding does not apply, and collapsed comes back false.

For a renamed file, pass the diff's old_path as old_path too. Without it the read is given only the new path, so it cannot see where the file came from and answers with the whole file as added.

Widen the surrounding context with context, which accepts 0 to 100 lines and defaults to 3. A file that is over the per-file ceiling even when asked for directly comes back with patch_truncated: true — read that one in line windows instead.

Read the lines around a change

A patch shows the changed lines and a few either side. When you need more — the rest of the function, the top of the file, or a file too large to patch at all — read a bounded window of lines at a commit. Nothing is diffed: you get the file as it stands at that commit.

Read the before side at the diff's base_sha and the after side at its head_sha — a file the change added exists only at the head, and one it deleted only at the base. has_more_before and has_more_after tell you whether another window exists in each direction, so you can walk a file without knowing its length up front.

List every file a change touches

Take the commit pair from the first page of the diff you opened — base_sha and head_sha, or diff.base_sha and diff.head_sha on a comparison or a stack — and ask for its file list. Every changed file comes back in one response, in the same order the pages use.

If truncated is true, the change touches more files than one list carries — see Limits. stats still counts every one of them.

Page through a diff by its commit pair

Once you know the pair, read further pages of the diff by the pair itself rather than by the merge request or the branches. The page is the same one the merge request would return — same page, limit, include_patch and collapse — but it cannot move: a push to the branch while you page does not change what you read.

Re-check a diff without downloading it again

Keep the ETag from any of the eight reads and send it back as If-None-Match. An answer that has not changed costs one header exchange and no body, which is what makes polling a merge request's diff every few seconds reasonable. Every option that changes the bytes is folded into the validator, so you never get a stale 304: on a batch read, including a page read by its commit pair, that means page, limit, include_patch and collapse; on the file list it is the pair alone; on a single-file diff it means the path, old_path and context; on a line window it means the path and the window you land on after clamping.

Reference

Limits

Diffs are bounded so that no single request can be unboundedly large. Every bound below announces itself in the response rather than failing, with one exception, and each one has a way through.

One more bound is not a number on this page, because it depends on your plan: the bytes you pull back. The batch reads — a commit diff, a merge request diff, a comparison, a stack diff and a page read by its commit pair — and the file list are metered against a per-hour and per-day outbound-data budget for you and for your namespace, and answer 429 TOO_MANY_REQUESTS once one is exhausted. Expanding a single file and reading a line window are not metered, which is the practical argument for reading stats first and expanding only what you open.

Every other number above is the same on every plan — none of them is a paid ceiling. Reading a diff creates nothing, so none of these reads counts against the quotas that cap how much you can create. For a file above the 1 MiB ceiling, fetch it with git from a clone; the ceiling applies to every file the API serves, and it is the same one a blob read enforces.

Troubleshooting

Examples

Reading a merge request the way a reviewer does, one file at a time, without pulling the whole change at once:

<your-repo-id> is the repository's id; <base_sha> and <head_sha> are the two values step 2 returned. Steps 3 to 6 stay consistent with step 2 no matter what lands on the branch in between, because they name commits rather than branches.

FAQ

Related