---
title: "Compare"
description: "Compare"
url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/javascript/reference/compare"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-22"
---

# Compare

## Compare

A branch comparison lists the content types and global fields that exist in only one of two branches, or that differ between them. The Compare class runs that comparison through the Content Management API (CMA). Use this class to

*   check what a merge would change before you call the [merge](/docs/developers/sdks/content-management-sdk/javascript/reference/branch#branch-merge) method
*   list the differences in content types, in global fields, or in both
*   read the differences of one content type or one global field

Call the [compare](/docs/developers/sdks/content-management-sdk/javascript/reference/branch#branch-compare) method on stack.branch('<BRANCH>') to get an object. The branch you call it on becomes the base branch, and the UID you pass becomes the compare branch.

## Instance State

*   Every Compare object has the same methods. There is no collection form and no item form.
*   Call stack.branch('<BRANCH>').compare('<COMPARE\_BRANCH>') to get an object that sends both branch UIDs on every request.
*   compare() without a UID, or with an empty string, returns an object that sends no branch UIDs. Every request from it fails, because the API requires compare\_branch.

## Class-Level Notes

**Branch UIDs.**

*   Every request sends base\_branch and compare\_branch as query parameters, from the values that [compare](/docs/developers/sdks/content-management-sdk/javascript/reference/branch#branch-compare) stored. A key of the same name in the params of a method replaces the stored value for that request.

**Results.**

*   Every method resolves to the response body as a plain object.
*   The API returns at most 100 differences per request. Use limit and skip to read more.

**Headers.**

*   **Known issue:** In 1.32.0, the comparison requests ignore headers that you change on the Compare object with [addHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-addheader), [addHeaderDict](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-addheaderdict) or [removeHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-removeheader). Change the header on the branch object before you call compare, for example stack.branch('<BRANCH>').addHeader('x-request-id', 'docs-123').compare('<COMPARE\_BRANCH>').
*   Every request sends the headers that the branch object held when you called compare.

**Rate limiting and retry.**

*   This SDK automatically retries on 429 with configurable delay and attempt limits.

**Additional Resource:** For more information on the retry options and their defaults, refer to the [Contentstack](/docs/developers/sdks/content-management-sdk/javascript/reference/contentstack) documentation.

## Capability Matrix

Capability

Supported

Notes / Alternative

Compare entries or assets

No

The API compares content types and global fields only.

Read all differences in one request

No

The API returns at most 100 differences per request. Page with skip.

Merge the differences

No

Use the [merge](/docs/developers/sdks/content-management-sdk/javascript/reference/branch#branch-merge) method of the [Branch](/docs/developers/sdks/content-management-sdk/javascript/reference/branch) class.

## Method Index

**Compare two branches.** Available on every Compare object.

Method Name

Returns

Description

[all](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-all)

The content types and global fields that differ between the two branches.

Lists every difference.

[contentTypes](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-contenttypes)

The content types that differ between the two branches.

Lists content type differences.

[globalFields](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-globalfields)

The global fields that differ between the two branches.

Lists global field differences.

**Set request headers.** Available on every Compare object.

Method Name

Returns

Description

[addHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-addheader)

The same compare object, for chaining.

Adds one request header.

[addHeaderDict](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-addheaderdict)

The same compare object, for chaining.

Adds several request headers.

[removeHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/compare#compare-removeheader)

The same compare object, for chaining.

Removes one request header.

## Class-Level Snippet

The snippet below compares a branch with main and prints the content type and global field differences.

```
import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const compare = stack.branch('main').compare('<COMPARE_BRANCH>')

try {
  const contentTypes = await compare.contentTypes({})
  const globalFields = await compare.globalFields({})
  console.log(JSON.stringify(contentTypes), JSON.stringify(globalFields))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}
```

## Methods

Each method of the Compare class has its own section below, with its parameters, validation rules, behavior, and examples.

## addHeader

addHeader adds one header to the requests that this compare object sends.

```
Returns: Compare. The same compare object, for chaining.
Known issue: In 1.32.0, the comparison requests ignore headers that you change on the Compare object. Add, change or remove the header on the branch object before you call compare, for example stack.branch('<BRANCH>').addHeader('x-request-id', 'docs-123').compare('<COMPARE_BRANCH>').ValidationThere is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.An invalid value surfaces as a rejected promise from the request method you call next.BehaviorClient-side only. addHeader sends no request.The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.The header map of this object changes, but the request methods of this object do not read it. See the known issue above.A key that the object already holds gets the new value.ExampleBasic usage: tag the requests of one compare objectimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.branch('<BRANCH>').compare('<COMPARE_BRANCH>').addHeader('x-request-id', 'docs-123')
console.log(target.stackHeaders['x-request-id'])
```

Header name, for example x-request-id.

Header value to send.

## addHeaderDict

addHeaderDict adds several headers at once to the requests that this compare object sends.

```
Returns: Compare. The same compare object, for chaining.
Known issue: In 1.32.0, the comparison requests ignore headers that you change on the Compare object. Add, change or remove the header on the branch object before you call compare, for example stack.branch('<BRANCH>').addHeader('x-request-id', 'docs-123').compare('<COMPARE_BRANCH>').ValidationThere is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.An invalid value surfaces as a rejected promise from the request method you call next.BehaviorClient-side only. addHeaderDict sends no request.addHeaderDict copies every key of headerDict into the header map of this object. A key that the object already holds gets the new value.The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.The header map of this object changes, but the request methods of this object do not read it. See the known issue above.ExampleBasic usage: add a request ID and a trace IDimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.branch('<BRANCH>').compare('<COMPARE_BRANCH>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
console.log(target.stackHeaders['x-request-id'], target.stackHeaders['x-trace-id'])
```

Header names and values to add.

## all

all lists the content types and global fields that exist in only one of the two branches or differ between them.

```
Returns: Promise<Response>. The content types and global fields that differ between the two branches.
ValidationThere is no client-side validation.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.The API rejects the request when the Compare object holds no compare branch, which happens when you call compare() without a UID.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorSends GET /v3/stacks/branches_compare with base_branch, compare_branch and every key of params as query parameters, as Compare branches describes.A base_branch or compare_branch key in params replaces the value that the Compare object holds.Resolves to the response body as a plain object.LimitationsThe API compares content types and global fields only.The API returns at most 100 differences per request. When more differences exist, the response carries a next URL. Use skip to read the next set.ExampleBasic usage: list every difference between main and another branchimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').all({})
  console.log(JSON.stringify(differences))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read the second set of 100 differencesimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').all({ limit: 100, skip: 100 })
  console.log(JSON.stringify(differences))
} catch (error) {
  console.error(error.errorMessage)
}
```

Query parameters for the comparison.

Maximum number of differences to return.

Number of differences to skip.

## contentTypes

contentTypes lists the content types that exist in only one of the two branches or differ between them, or the differences of one content type.

```
Returns: Promise<Response>. The content types that differ between the two branches.
ValidationThere is no client-side validation.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.The API rejects the request when the Compare object holds no compare branch, which happens when you call compare() without a UID.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorWithout params.uid, sends GET /v3/stacks/branches_compare/content_types, as Compare content types between branches describes.With params.uid, sends GET /v3/stacks/branches_compare/content_types/{content_type_uid}, as Compare specific content type between branches describes. The SDK puts the UID in the path, not in the query string.Each request carries base_branch, compare_branch and every other key of params as query parameters. A base_branch or compare_branch key in params replaces the value that the Compare object holds.contentTypes deletes the uid key from the object you pass. Build a new object for each call when you reuse the values.Resolves to the response body as a plain object.The API returns at most 100 differences per request. Use skip to read the next set.To compare global fields, use the globalFields method. To compare both at once, use the all method.ExampleBasic usage: list the content types that differ between main and another branchimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').contentTypes({})
  console.log(JSON.stringify(differences))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: page through the content types that differimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').contentTypes({ limit: 100, skip: 100 })
  console.log(JSON.stringify(differences))
} catch (error) {
  console.error(error.errorMessage)
}Edge case: compare one content type, with its schemasimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // The SDK moves uid into the URL path and sends include_schemas as a query parameter
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').contentTypes({ uid: '<CONTENT_TYPE_UID>', include_schemas: true })
  console.log(JSON.stringify(differences))
} catch (error) {
  console.error(error.errorMessage)
}
```

Query parameters, and the optional content type UID.

UID of one content type to compare.

Maximum number of differences to return.

Number of differences to skip.

Adds the schemas to a one-content type comparison.

## globalFields

globalFields lists the global fields that exist in only one of the two branches or differ between them, or the differences of one global field.

```
Returns: Promise<Response>. The global fields that differ between the two branches.
ValidationThere is no client-side validation.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.The API rejects the request when the Compare object holds no compare branch, which happens when you call compare() without a UID.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorWithout params.uid, sends GET /v3/stacks/branches_compare/global_fields, as Compare global fields between branches describes.With params.uid, sends GET /v3/stacks/branches_compare/global_fields/{global_field_uid}, as Compare specific global field between branches describes. The SDK puts the UID in the path, not in the query string.Each request carries base_branch, compare_branch and every other key of params as query parameters. A base_branch or compare_branch key in params replaces the value that the Compare object holds.globalFields deletes the uid key from the object you pass. Build a new object for each call when you reuse the values.Resolves to the response body as a plain object.The API returns at most 100 differences per request. Use skip to read the next set.To compare content types, use the contentTypes method. To compare both at once, use the all method.ExampleBasic usage: list the global fields that differ between main and another branchimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').globalFields({})
  console.log(JSON.stringify(differences))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: page through the global fields that differimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').globalFields({ limit: 100, skip: 100 })
  console.log(JSON.stringify(differences))
} catch (error) {
  console.error(error.errorMessage)
}Edge case: compare one global field, with its schemasimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // The SDK moves uid into the URL path and sends include_schemas as a query parameter
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').globalFields({ uid: '<GLOBAL_FIELD_UID>', include_schemas: true })
  console.log(JSON.stringify(differences))
} catch (error) {
  console.error(error.errorMessage)
}
```

Query parameters, and the optional global field UID.

UID of one global field to compare.

Maximum number of differences to return.

Number of differences to skip.

Adds the schemas to a one-global field comparison.

## removeHeader

removeHeader removes one header from the requests that this compare object sends.

```
Returns: Compare. The same compare object, for chaining.
Known issue: In 1.32.0, the comparison requests ignore headers that you change on the Compare object. Add, change or remove the header on the branch object before you call compare, for example stack.branch('<BRANCH>').addHeader('x-request-id', 'docs-123').compare('<COMPARE_BRANCH>').ValidationThere is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.An invalid value surfaces as a rejected promise from the request method you call next.BehaviorClient-side only. removeHeader sends no request.The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.The header map of this object changes, but the request methods of this object do not read it. See the known issue above.removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.Do not remove api_key. Without it, the API cannot tell which stack the request is for.ExampleBasic usage: drop a header that you added earlierimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const target = stack.branch('<BRANCH>').compare('<COMPARE_BRANCH>')
  .addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
  .removeHeader('x-trace-id')
console.log('x-trace-id' in target.stackHeaders) // false
```

Name of the header to remove.

## Compare | JavaScript Management SDK | Contentstack

The Compare class in the JavaScript Management SDK lists the content types and global fields that differ between two branches of a stack.