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 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
| 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 method of the Branch class. |
Method Index
Compare two branches. Available on every Compare object.
| Method Name | Returns | Description |
|---|---|---|
| all | The content types and global fields that differ between the two branches. | Lists every difference. |
| contentTypes | The content types that differ between the two branches. | Lists content type differences. |
| 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 | The same compare object, for chaining. | Adds one request header. |
| addHeaderDict | The same compare object, for chaining. | Adds several request headers. |
| 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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
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.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the comparison. |
| params.limit | number | Maximum number of differences to return. |
| params.skip | number | Number of differences to skip. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, and the optional content type UID. |
| params.uid | string | UID of one content type to compare. |
| params.limit | number | Maximum number of differences to return. |
| params.skip | number | Number of differences to skip. |
| params.include_schemas | boolean | Adds the schemas to a one-content type comparison. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, and the optional global field UID. |
| params.uid | string | UID of one global field to compare. |
| params.limit | number | Maximum number of differences to return. |
| params.skip | number | Number of differences to skip. |
| params.include_schemas | boolean | Adds the schemas to a one-global field comparison. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
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