Commits comparison¶

GET /api/v5/repos/{owner}/{repo}/compare/{base}...{head}

This endpoint returns the comparison result between two commits in the specified repository. You can use a commit SHA, branch name, or tag name as the start and end points of the comparison, and it returns the list of commits within the comparison range, the changed files, and the number of added and deleted lines.

Access token support¶

AtomGit user access tokens

Anonymous access¶

This endpoint allows anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Address path of the namespace that owns the repository (address path of the enterprise, organization, or user)
`repo`	path	string	Yes	Repository path (path)
`base`	path	string	Yes	Start point of the comparison. Commit SHA, branch name, or tag name
`head`	path	string	Yes	End point of the comparison. Commit SHA, branch name, or tag name
`straight`	query	boolean	No	Whether to compare directly; defaults to `false`
`suffix`	query	string	No	Filter files by file extension, such as `.txt`; affects only `files`

Response parameters¶

Field	Type	Always returned	Nullable	Description
`base_commit`	object	Yes	No	Start commit of the comparison
`merge_base_commit`	object	Yes	No	Merge base commit
`commits`	object[]	Yes	No	List of commits within the comparison range
`files`	object[]	Yes	No	List of changed files
`truncated`	integer	Yes	No	Whether the response is truncated (`0`/`1`)

base_commit object (merge_base_commit has the same structure)

Field	Type	Always returned	Nullable	Description
`base_commit.url`	string	Yes	No	API URL of the commit
`base_commit.sha`	string	Yes	No	Commit SHA
`base_commit.html_url`	string	Yes	No	Web page URL of the commit
`base_commit.comments_url`	string	Yes	No	API URL of the commit comments
`base_commit.commit`	object	Yes	No	Commit metadata
`base_commit.author`	object	Yes	No	Commit author
`base_commit.committer`	object	Yes	No	Committer
`base_commit.parents`	object[]	Yes	No	List of parent commits

`base_commit.commit` object¶

Field	Type	Always returned	Nullable	Description
`base_commit.commit.author`	object	Yes	No	Commit author information
`base_commit.commit.committer`	object	Yes	No	Committer information
`base_commit.commit.tree`	object	Yes	No	Tree for the commit
`base_commit.commit.message`	string	Yes	No	Commit information

`base_commit.commit.author` object (`base_commit.commit.committer` has the same structure)¶

Field	Type	Always returned	Nullable	Description
`base_commit.commit.author.name`	string	Yes	No	Author name
`base_commit.commit.author.date`	string	Yes	No	Commit date (ISO 8601 format)
`base_commit.commit.author.email`	string	Yes	No	Author email

`base_commit.commit.tree` object¶

Field	Type	Always returned	Nullable	Description
`base_commit.commit.tree.sha`	string	Yes	No	SHA of the tree
`base_commit.commit.tree.url`	string	Yes	No	API URL of the tree

`base_commit.author` object (`base_commit.committer` has the same structure)¶

Field	Type	Always returned	Nullable	Description
`base_commit.author.name`	string	Yes	No	Username
`base_commit.author.id`	integer	Yes	No	User ID
`base_commit.author.login`	string	Yes	No	Login name
`base_commit.author.type`	string	Yes	No	User type, such as `User`

`base_commit.parents` array element¶

Field	Type	Always returned	Nullable	Description
`base_commit.parents.sha`	string	Yes	No	Parent commit SHA
`base_commit.parents.url`	string	Yes	No	API URL of the parent commit

`commits` array element¶

Field	Type	Always returned	Nullable	Description
`commits.sha`	string	Yes	No	Commit SHA
`commits.commit`	object	Yes	No	Commit metadata
`commits.author`	object	Yes	No	Commit author
`commits.committer`	object	Yes	No	Committer

`commits.commit` object¶

Field	Type	Always returned	Nullable	Description
`commits.commit.author`	object	Yes	No	Commit author information
`commits.commit.committer`	object	Yes	No	Committer information
`commits.commit.message`	string	Yes	No	Commit information

`commits.commit.author` object (`commits.commit.committer` has the same structure)¶

Field	Type	Always returned	Nullable	Description
`commits.commit.author.name`	string	Yes	No	Author name
`commits.commit.author.date`	string	Yes	No	Commit date (ISO 8601 format)
`commits.commit.author.email`	string	Yes	No	Author email

`commits.author` object (`commits.committer` has the same structure)¶

Field	Type	Always returned	Nullable	Description
`commits.author.name`	string	Yes	No	Username
`commits.author.id`	integer	Yes	No	User ID
`commits.author.login`	string	Yes	No	Login name

`files` array element¶

Field	Type	Always returned	Nullable	Description
`files.sha`	string	Yes	No	File blob SHA
`files.filename`	string	Yes	No	File name
`files.status`	string	Yes	No	File change status (such as `added`)
`files.additions`	integer	Yes	No	Lines added
`files.deletions`	integer	Yes	No	Lines deleted
`files.changes`	integer	Yes	No	Total lines changed
`files.blob_url`	string	Yes	No	File blob URL
`files.raw_url`	string	Yes	No	Raw file URL
`files.patch`	string	Yes	No	File change patch (diff)
`files.truncated`	integer	Yes	No	Whether the patch is truncated (`0`/`1`)

Error response¶

The endpoint may return status codes other than 200, and callers should handle errors accordingly.

400 Parameter error

{
  "error": "invalid_request",
  "message": "Parameter base cannot be empty"
}

404 Resource not found

{
  "error": "not_found",
  "message": "Repository or commit not found"
}

Note: The actual error field names are those returned by the backend.

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Parameter error
`401`	Authentication required
`403`	Forbidden
`404`	Repository or commit not found
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Request example¶

Parameter description¶

The example does not include authentication headers (this endpoint allows anonymous access). If you need authentication, you can include an AtomGit user access token.

Replace <owner> with the address path of the namespace that owns the repository (address path of the enterprise, organization, or user); Replace <repo> with the repository path (path); Replace <base> with the start point of the comparison (commit SHA, branch name, or tag name); Replace <head> with the end point of the comparison (commit SHA, branch name, or tag name).

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/compare/<base>...<head>' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/compare/<base>...<head>",
  {
    headers: {
      "Accept": "application/json",
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/compare/<base>...<head>",
    headers={
        "Accept": "application/json",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "base_commit": {
    "url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<sha>",
    "sha": "<sha>",
    "html_url": "https://api.atomgit.com/<owner>/<repo>/commit/<sha>",
    "comments_url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<sha>/comments",
    "commit": {
      "author": {
        "name": "octocat",
        "date": "2024-08-13T11:34:35Z",
        "email": "octocat@noreply.atomgit.com"
      },
      "committer": {
        "name": "octocat",
        "date": "2024-08-13T11:34:35Z",
        "email": "octocat@noreply.atomgit.com"
      },
      "tree": {
        "sha": "<tree-sha>",
        "url": "https://api.atomgit.com/repos/<owner>/<repo>/git/trees/<tree-sha>"
      },
      "message": "new: add file test.py"
    },
    "author": {
      "name": "octocat",
      "id": 953,
      "login": "octocat",
      "type": "User"
    },
    "committer": {
      "name": "octocat",
      "id": 953,
      "login": "octocat",
      "type": "User"
    },
    "parents": [
      {
        "sha": "<parent-sha>",
        "url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<parent-sha>"
      }
    ]
  },
  "merge_base_commit": {
    "url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<sha>",
    "sha": "<sha>",
    "html_url": "https://api.atomgit.com/<owner>/<repo>/commit/<sha>",
    "comments_url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<sha>/comments",
    "commit": {
      "author": {
        "name": "octocat",
        "date": "2024-08-13T11:34:35Z",
        "email": "octocat@noreply.atomgit.com"
      },
      "committer": {
        "name": "octocat",
        "date": "2024-08-13T11:34:35Z",
        "email": "octocat@noreply.atomgit.com"
      },
      "tree": {
        "sha": "<tree-sha>",
        "url": "https://api.atomgit.com/repos/<owner>/<repo>/git/trees/<tree-sha>"
      },
      "message": "new: add file test.py"
    },
    "author": {
      "name": "octocat",
      "id": 953,
      "login": "octocat",
      "type": "User"
    },
    "committer": {
      "name": "octocat",
      "id": 953,
      "login": "octocat",
      "type": "User"
    },
    "parents": [
      {
        "sha": "<parent-sha>",
        "url": "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/commits/<parent-sha>"
      }
    ]
  },
  "commits": [
    {
      "sha": "<sha>",
      "commit": {
        "author": {
          "name": "octocat",
          "date": "2024-09-09T07:29:23Z",
          "email": "octocat@noreply.atomgit.com"
        },
        "committer": {
          "name": "octocat",
          "date": "2024-09-09T07:29:23Z",
          "email": "octocat@noreply.atomgit.com"
        },
        "message": "new: add file bbb.rs"
      },
      "author": {
        "name": "octocat",
        "id": 953,
        "login": "octocat"
      },
      "committer": {
        "name": "octocat",
        "id": 953,
        "login": "octocat"
      }
    }
  ],
  "files": [
    {
      "sha": "<blob-sha>",
      "filename": "bbb.rs",
      "status": "added",
      "additions": 3,
      "deletions": 0,
      "changes": 3,
      "blob_url": "https://api.atomgit.com/<owner>/<repo>/blob/<blob-sha>/bbb.rs",
      "raw_url": "https://api.atomgit.com/<owner>/<repo>/raw/<blob-sha>/bbb.rs",
      "patch": "@@ -0,0 +1,3 @@\n+\n+\n+println!(\"hello\")",
      "truncated": 0
    }
  ],
  "truncated": 0
}

Error codes¶

Error code	Description
`400`	Parameter error or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`403`	Forbidden
`404`	The requested path does not exist
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc