Compare

View as Markdown

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 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 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 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, addHeaderDict or 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 documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Compare entries or assetsNoThe API compares content types and global fields only.
Read all differences in one requestNoThe API returns at most 100 differences per request. Page with skip.
Merge the differencesNoUse the merge method of the Branch class.

Method Index

Compare two branches. Available on every Compare object.

Method NameReturnsDescription
allThe content types and global fields that differ between the two branches.Lists every difference.
contentTypesThe content types that differ between the two branches.Lists content type differences.
globalFieldsThe global fields that differ between the two branches.Lists global field differences.

Set request headers. Available on every Compare object.

Method NameReturnsDescription
addHeaderThe same compare object, for chaining.Adds one request header.
addHeaderDictThe same compare object, for chaining.Adds several request headers.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

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>').

Validation

  • There 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.

Behavior

  • Client-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.

Example

Basic usage: tag the requests of one compare object

import 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'])

addHeaderDict

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

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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>').

Validation

  • There 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.

Behavior

  • Client-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.

Example

Basic usage: add a request ID and a trace ID

import 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'])

all

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

NameTypeDescription
paramsobject

Query parameters for the comparison.

Default: {}
params.limitnumber

Maximum number of differences to return.

Default: API default (100)
params.skipnumber

Number of differences to skip.

Default: API default

Returns: Promise<Response>. The content types and global fields that differ between the two branches.

Validation

  • There 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.

Behavior

  • Sends 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.

Limitations

  • The 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.

Example

Basic usage: list every difference between main and another branch

import 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 differences

import 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)
}

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.

NameTypeDescription
paramsobject

Query parameters, and the optional content type UID.

Default: {}
params.uidstring

UID of one content type to compare.

Default: undefined (compares all content types)
params.limitnumber

Maximum number of differences to return.

Default: API default (100)
params.skipnumber

Number of differences to skip.

Default: API default
params.include_schemasboolean

Adds the schemas to a one-content type comparison.

Default: API default

Returns: Promise<Response>. The content types that differ between the two branches.

Validation

  • There 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.

Behavior

  • Without 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.

Example

Basic usage: list the content types that differ between main and another branch

import 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 differ

import 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 schemas

import 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)
}

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.

NameTypeDescription
paramsobject

Query parameters, and the optional global field UID.

Default: {}
params.uidstring

UID of one global field to compare.

Default: undefined (compares all global fields)
params.limitnumber

Maximum number of differences to return.

Default: API default (100)
params.skipnumber

Number of differences to skip.

Default: API default
params.include_schemasboolean

Adds the schemas to a one-global field comparison.

Default: API default

Returns: Promise<Response>. The global fields that differ between the two branches.

Validation

  • There 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.

Behavior

  • Without 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.

Example

Basic usage: list the global fields that differ between main and another branch

import 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 differ

import 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 schemas

import 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)
}

removeHeader

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

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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>').

Validation

  • There 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.

Behavior

  • Client-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.

Example

Basic usage: drop a header that you added earlier

import 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