Skip to content
forgit api docs

Compare two commits

GET
/repositories/{workspace}/{repo_slug}/diff/{spec}

Produces a raw git-style diff.

Single commit spec

If the spec argument to this API is a single commit, the diff is produced against the first parent of the specified commit.

Two commit spec

Two commits separated by .. may be provided as the spec, e.g., 3a8b42..9ff173. When two commits are provided and the topic query parameter is true, this API produces a 2-way three dot diff. This is the diff between source commit and the merge base of the source commit and the destination commit. When the topic query param is false, a simple git-style diff is produced.

The two commits are interpreted as follows:

  • First commit: the commit containing the changes we wish to preview
  • Second commit: the commit representing the state to which we want to compare the first commit
  • Note: This is the opposite of the order used in git diff.

Comparison to patches

While similar to patches, diffs:

  • Don’t have a commit header (username, commit message, etc)
  • Support the optional path=foo/bar.py query param to filter the diff to just that one file diff

Response

The raw diff is returned as-is, in whatever encoding the files in the repository use. It is not decoded into unicode. As such, the content-type is text/plain.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
repo_slug
required
string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

spec
required
string

A commit SHA (e.g. 3a8b42) or a commit range using double dot notation (e.g. 3a8b42..9ff173).

workspace
required
string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Query Parameters

Section titled “ Query Parameters ”
context
integer

Generate diffs with lines of context instead of the usual three.

path
string

Limit the diff to a particular file (this parameter can be repeated for multiple paths).

ignore_whitespace
boolean

Generate diffs that ignore whitespace.

binary
boolean

Generate diffs that include binary files, true if omitted.

renames
boolean

Whether to perform rename detection, true if omitted.

merge
boolean

This parameter is deprecated. The ‘topic’ parameter should be used instead. The ‘merge’ and ‘topic’ parameters cannot be both used at the same time.

If true, the source commit is merged into the destination commit, and then a diff from the destination to the merge result is returned. If false, a simple ‘two dot’ diff between the source and destination is returned. True if omitted.

topic
boolean

If true, returns 2-way ‘three-dot’ diff. This is a diff between the source commit and the merge base of the source commit and the destination commit. If false, a simple ‘two dot’ diff between the source and destination is returned.

If omitted, defaults to true, ie. a 2 way ‘three-dot’ diff is returned.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

The raw diff

555

Section titled “ 555 ”

If the diff was too large and timed out.

Since this endpoint does not employ any form of pagination, but instead returns the diff as a single document, it can run into trouble on very large diffs. If Bitbucket times out in cases like these, a 555 status code is returned.

Media type application/json
Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object
type
required
string
error
object
message
required
string
detail
string
data

Optional structured data that is endpoint-specific.

object
key
additional properties
any
key
additional properties
any
Example generated 
{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}