Comparing Branches, Tags, and Commits

Function

This API is used for branch, tag, and commit comparison.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

GET https://{hostURL}/v4/repositories/{repository_id}/compare

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
repository_id	Yes	Integer	Definition You can query the project list to obtain the repository ID by calling the API used to query user's all repositories. Constraints N/A. Value range: 1~2147483647

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
from	Yes	String	Definition Name of the branch, label, or commit ID to be compared. Range 1–100,000 characters.
to	Yes	String	Definition Name of the branch, label, or ID of the commit to be stopped for comparison. Range 1–100,000 characters.
compare_type	No	String	Definition Comparison type. Range branch: indicates branch. commit: indicates commit. tag: indicates label. Default value: branch Enumeration values: branch commit tag
target_id	No	Integer	Definition Target repository of the MR. The default value is the repository ID. Value range: 1~2147483647
straight	No	Boolean	Definition Comparison method. Range true: direct comparison between 'from' and 'to' ('from'..'to'). false: use merge base for comparison ('from'...'to'). Default value: false
ignore_whitespace_change	No	Boolean	Definition Whether to ignore the change of blank quantity. Range true: ignore the change of blank quantity. false: not to ignore the change of blank quantity. Default value: false
view	No	String	Definition Whether to ignore the change of blank quantity. Range count: indicates count of number. commits: indicates commit information. diffs: indicates difference information. files: indicates file information. commits and diffs: indicate commit information and difference information. Enumeration values: count commits diffs files commits,diffs
only_count	No	Boolean	Definition Whether to return only results containing the commit count and difference count. Range true: return only results containing the commit count and difference count are returned. false: return result information according to the compare_view parameter. Default value: false
file_path	No	String	Definition Returns different results based on the given file path. If the file has been renamed, file_path must contain old_path and new_path, for example, "file_path=old_path,new_path". Range 1–100,000 characters.
additional_fields	No	String	Definition Returns different results based on the given parameters. Range change_lines, number of changed lines. Enumeration values: change_lines
offset	No	Integer	Definition Offset, which starts from 0. Value range: 0~2147483647 Default value: 0
limit	No	Integer	Definition Number of returned records. Value range: 1~100 Default value: 20

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. Obtain a token by calling the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the user token. Constraints Mandatory. Range 1–100,000 characters. Default Value N/A.

Response Parameters

Status code: 200

**Table 4** Response header parameters
Parameter	Type	Description
X-Total	String	Commit, branch, and tag comparison result.

**Table 5** Response body parameters
Parameter	Type	Description
commit	CommitDto object	Commit information
commits	Array of CommitDto objects	Commit information list
diffs	Array of DiffDto objects	Chang file information
diffs_files	Array of DiffDto objects	Chang file information
compare_timeout	Boolean	Timed out or not
compare_same_ref	Boolean	Same or not
conflict_files	Array of ConflictFileDto objects	Conflict file
added_lines	Integer	Number of added lines Value range: 1~2147483647
removed_lines	Integer	Number of deleted lines Value range: 1~2147483647
commits_count	Integer	Number of commits Value range: 1~2147483647
diffs_count	Integer	Number of changed files Value range: 1~2147483647

**Table 6** CommitDto
Parameter	Type	Description
id	String	id
message	String	Message
parent_ids	Array of strings	Parent node commit ID
authored_date	String	Time when the branch was created.
author_name	String	Creator name
author_email	String	Creator's email.
committed_date	String	Code commit date and time
committer_name	String	Committer name
committer_email	String	Committer email
open_gpg_verified	Boolean	Whether to enable the GPG verification
verification_status	Integer	Verification status Value range: 0~1
gpg_primary_key_id	String	Identifier of the GPG public key
name	String	Username
gpg_nick_name	String	Alias
gpg_tenant_name	String	Tenant name
gpg_user_name	String	Information about a specific GPG user
short_id	String	Short ID
created_at	String	Creation time
title	String	Title
author_avatar_url	String	author_avatar_url
committer_avatar_url	String	committer_avatar_url
relate_url	Array of RelatedCommitSimpleDto objects	only for DevCloud
nick_name	String	Title
tenant_name	String	tenant_name
user_name	String	Username

**Table 7** RelatedCommitSimpleDto
Parameter	Type	Description
related_id	String	Associated work item ID
related_url	String	Associated work item URL

**Table 8** DiffDto
Parameter	Type	Description
old_path	String	Old file
new_path	String	New file
a_mode	String	Old file type.
b_mode	String	New file type
file_path	String	File path
new_file	Boolean	New or not
file_type	String	File type
renamed_file	Boolean	Rename or not
deleted_file	Boolean	Whether to delete a file
diff	String	Comparison result
binary	Boolean	Binary or not
too_large	Boolean	Whether the file is too large
collapsed	Boolean	Collapsed or not
line_count	Array of integers	Value range: 1~2147483647
added_lines	Integer	Number of added lines Value range: 1~2147483647
removed_lines	Integer	Number of deleted lines Value range: 1~2147483647

**Table 9** ConflictFileDto
Parameter	Type	Description
old_path	String	Old file
new_path	String	New file

Status code: 401

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error message.

Status code: 403

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error message.

Status code: 404

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error message.

Example Requests

None

Example Responses

Status code: 200

Branch, tag, and commit comparison

{
  "commit" : {
    "id" : "1690246aeae929d672740fc4951db94ae635e493",
    "message" : "Connect MySQL to \\n\\nChange-Id: I06d0995d1362beff8ed530.",
    "parent_ids" : "[test01,test02]",
    "authored_date" : "2024-10-25T09:28:10.000Z",
    "author_name" : "test",
    "author_email" : "test@example.com",
    "committed_date" : "2024-10-25T09:28:10.000Z",
    "committer_name" : "test_name",
    "committer_email" : "test@example.com",
    "open_gpg_verified" : null,
    "verification_status" : 0,
    "gpg_primary_key_id" : "",
    "short_id" : "123",
    "created_at" : "2024-10-25T09:28:10.000Z",
    "title" : "test",
    "author_avatar_url" : "https://test",
    "committer_avatar_url" : "https://test",
    "relate_url" : null
  },
  "commits" : null,
  "diffs" : null,
  "diffs_files" : null,
  "compare_timeout" : null,
  "compare_same_ref" : null,
  "conflict_files" : null,
  "added_lines" : 2,
  "removed_lines" : 2,
  "commits_count" : 2,
  "diffs_count" : 2
}

Status code: 401

Unauthorized

{
  "error_code" : "CH.00000001",
  "error_msg" : "User authentication info not found."
}

Status code: 403

Bad Request

{
  "error_code" : "CH.00401008",
  "error_msg" : "Insufficient permissions. Apply for the required permissions and try again."
}

Status code: 404

Not Found

{
  "error_code" : "CH.00402000",
  "error_msg" : "The repository does not exist. Check and try again."
}

Status Codes

Status Code	Description
200	Branch, tag, and commit comparison
401	Unauthorized
403	Bad Request
404	Not Found

Error Codes

See Error Codes.

Parent topic: Repository

Previous topic: Obtaining Repository Dynamics

Next topic: Querying Commit File Content by Line

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.