Experimental

Compare two exact source trees

Compare source changes between two package versions or two refs in a public repository. The response lists changed files and can include added and deleted line counts and patches.

Use this experimental endpoint to inspect the code behind a release or upgrade. Comparisons cover the whole repository, including when you identify it through a package.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`files`	Identity/status fields and content safety; inventory only	No
`files.stats`	Adds nullable additions/deletions; implies `files` and requests stats	No
`files.patch`	Adds nullable patch and omission reason; implies stats and requests patches	Yes

POST

experimental

code

diff

POST /v1/experimental/code/diff HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>
Content-Type: application/json

{"registry":"npm","name":"express","from_version":"4.21.2","to_version":"5.1.0"}

{
  "content_coverage": "failed",
  "content_failure": {
    "code": "UPSTREAM_ERROR",
    "limit_kind": null,
    "retry_after_ms": 2500,
    "retryable": true,
    "stage": "content"
  },
  "files": [
    {
      "additions": 2,
      "content_omission_reason": null,
      "content_safety": {
        "filtered": false,
        "modifications": []
      },
      "content_status": "patch",
      "deletions": 1,
      "mode_changed": false,
      "patch": "@@ -1 +1,2 @@\n-old\n+new",
      "path": "lib/application.js",
      "path_encoding": "utf8",
      "status": "modified",
      "type_changed": false
    }
  ],
  "from_resolution": {
    "commit_sha": "0123456789abcdef0123456789abcdef01234567",
    "ref": "refs/tags/4.21.2",
    "ref_kind": "tag",
    "requested": "4.21.2",
    "resolved_version": "4.21.2",
    "version_source": "registry"
  },
  "has_more_files": false,
  "package": {
    "name": "express",
    "registry": "npm",
    "repo_url": "https://github.com/expressjs/express"
  },
  "scope": {
    "from_subpath": null,
    "path_glob": null,
    "path_prefix": null,
    "status": "repository",
    "to_subpath": null
  },
  "summary": {
    "added": 0,
    "deleted": 0,
    "files_changed": 1,
    "inventory_complete": true,
    "mode_changed": 0,
    "modified": 1,
    "type_changed": 0,
    "unprojectable_files": 0
  },
  "to_resolution": {
    "commit_sha": "fedcba9876543210fedcba9876543210fedcba98",
    "ref": "refs/tags/5.1.0",
    "ref_kind": "tag",
    "requested": "5.1.0",
    "resolved_version": "5.1.0",
    "version_source": "registry"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional trimmed printable ASCII client name, maximum 80 bytes.

X-GitHits-Client-Version

string

Optional trimmed printable ASCII client version, maximum 80 bytes.

X-GitHits-Agent

string

Optional trimmed printable ASCII agent attribution, maximum 160 bytes.

X-GitHits-Session-ID

string

Optional session attribution, maximum 128 printable ASCII bytes; malformed values are dropped.

Query Parameters

fields

string

default:files.patch

Finite comma-separated selectors: files, files.stats, and files.patch. The default is files.patch. Dependencies are additive; repeated selector tokens are idempotent. Unknown, empty, leaf, and wildcard selectors, plus repeated fields query parameters, are rejected.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Maximum string length: 2048

Body

application/json

Compare two package versions or two repository refs.

from_ref

string

Explicit base ref, at most 255 UTF-8 bytes.

from_version

string

Base package version or registry-compatible constraint.

max_files

integer<int32>

default:50

Maximum relevance-ranked files returned after filtering.

Required range: 1 <= x <= 300

max_patch_bytes

integer<int32>

default:262144

Total patch-byte budget, used only when files.patch is selected.

Required range: 1024 <= x <= 2097152

name

string

Package name; requires registry and both version endpoints.

path_glob

string

Repository-relative bounded glob intersected with path_prefix.

path_prefix

string

Repository-relative component prefix, normalized without edge slashes.

registry

enum<string>

Package registry; requires name and both version endpoints.

Available options:

npm,

pypi,

hex,

crates,

vcpkg,

zig,

nuget,

maven,

packagist,

rubygems,

go,

swift

repo_url

string

Supported credential-free public GitHub, GitLab or Codeberg URL.

to_ref

string

Explicit head ref, at most 255 UTF-8 bytes.

to_version

string

Head package version or registry-compatible constraint.

Response

Exact-tree inventory and selected content evidence

Resolved commits, complete inventory counts, and selected file details.

content_coverage

enum<string>

required

Coverage of optional content for returned files.

Available options:

not_requested,

complete,

partial,

failed

content_failure

null | object

required

Bounded content-phase failure; null unless content_coverage is failed.

Show child attributes

files

object[]

required

Files in relevance order, limited by max_files; paths that cannot be represented are omitted.

Show child attributes

from_resolution

object

required

Immutable base-side resolution used by the diff.

Show child attributes

has_more_files

boolean

required

Whether additional matching files with representable paths were omitted by max_files.

package

null | object

required

Canonical package identity; null for repository addressing.

Show child attributes

scope

object

required

Effective repository inventory scope and caller filters.

Show child attributes

summary

object

required

Complete caller-filtered repository inventory counts before file projection.

Show child attributes

to_resolution

object

required

Immutable head-side resolution used by the diff.

Show child attributes

⌘I

POST /v1/experimental/code/diff HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>
Content-Type: application/json

{"registry":"npm","name":"express","from_version":"4.21.2","to_version":"5.1.0"}

{
  "content_coverage": "failed",
  "content_failure": {
    "code": "UPSTREAM_ERROR",
    "limit_kind": null,
    "retry_after_ms": 2500,
    "retryable": true,
    "stage": "content"
  },
  "files": [
    {
      "additions": 2,
      "content_omission_reason": null,
      "content_safety": {
        "filtered": false,
        "modifications": []
      },
      "content_status": "patch",
      "deletions": 1,
      "mode_changed": false,
      "patch": "@@ -1 +1,2 @@\n-old\n+new",
      "path": "lib/application.js",
      "path_encoding": "utf8",
      "status": "modified",
      "type_changed": false
    }
  ],
  "from_resolution": {
    "commit_sha": "0123456789abcdef0123456789abcdef01234567",
    "ref": "refs/tags/4.21.2",
    "ref_kind": "tag",
    "requested": "4.21.2",
    "resolved_version": "4.21.2",
    "version_source": "registry"
  },
  "has_more_files": false,
  "package": {
    "name": "express",
    "registry": "npm",
    "repo_url": "https://github.com/expressjs/express"
  },
  "scope": {
    "from_subpath": null,
    "path_glob": null,
    "path_prefix": null,
    "status": "repository",
    "to_subpath": null
  },
  "summary": {
    "added": 0,
    "deleted": 0,
    "files_changed": 1,
    "inventory_complete": true,
    "mode_changed": 0,
    "modified": 1,
    "type_changed": 0,
    "unprojectable_files": 0
  },
  "to_resolution": {
    "commit_sha": "fedcba9876543210fedcba9876543210fedcba98",
    "ref": "refs/tags/5.1.0",
    "ref_kind": "tag",
    "requested": "5.1.0",
    "resolved_version": "5.1.0",
    "version_source": "registry"
  }
}

Get started

v1 reference

Compare two exact source trees

Selector catalogue

Authorizations

Headers

Query Parameters

Body

Response