Contentful Merge

Introduction | Features | Installation | Usage | Commands | Data structure | FAQ | Feedback | Code of Conduct | License

Introduction

Contentful

Contentful provides content infrastructure for digital teams to power websites, apps, and devices. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enables developers and content creators to ship their products faster.

Contentful Merge

The contentful-merge CLI tool allows you to compare and merge entries across environments in a Contentful space. It can be used to create a changeset of all entry differences between two environments, and to apply this changeset to another environment, thereby effectively syncing the content of two environments.

Tracking

• We want to know how people are using this tool, so that we can prioritize what to focus on next. We therefore collect some analytics data.
• We would love your feedback! Here is a form where you can tell us about your experience and let us know which additional features you would like.

---

Features

Takes a space id and two environment ids and creates a changeset which details all entry differences between the two environments.

• It uses the Contentful Delivery API (CDA) to fetch all data.
• A custom CDA client executes requests in the different environments in parallel.
• All requests are batched.
• In order to identify added and deleted entries, entry ids are compared in both environments.
• In order to identify updated entries, comparison happens in two steps: The initial step involves identifying potentially diverging entries by examining the sys.changedAt property of all entries present in both environments. Subsequently, for all entries with distinct sys.changedAt values, a more comprehensive comparison of their payload is performed. If any variations are found, a patch is generated to reflect the differences.

:bulb: Want to merge content types instead of entries? :bulb: We got you covered: Take a look at the Merge App to your space, or, if you prefer the command line, check out the Merge CLI.

Installation

Prerequisite: node v18

1npm install -g contentful-merge

Usage

1$ npm install -g contentful-merge
2$ contentful-merge COMMAND
3running command...
4$ contentful-merge (--version)
5contentful-merge/0.0.0 darwin-arm64 node-v20.2.0
6$ contentful-merge --help [COMMAND]
7USAGE
8  $ contentful-merge COMMAND
9...

Commands

• contentful-merge create
• contentful-merge apply
• contentful-merge help [COMMANDS]

contentful-merge create

Create Entries Changeset

USAGE
  $ contentful-merge create --space <value> --source <value> --target <value> --cda-token <value> [--request-batch-size <value>] [--output-file <value>] [--query-entries <value>] [--allowed-operations <value>]

FLAGS
  --cda-token=<value>           (required) CDA token, defaults to env: $CDA_TOKEN
  --host=<value>                [default: api.contentful.com] Contentful API host
  --query-entries=<value>       Query parameters for entries based on CDA. You can pass multiple query-entries flags.
  --allowed-operations=<value>  [default: add,delete,update] Allowed operations for changeset. You can pass multiple allowed-operations flags.
  --output-file=<value>         File path to changeset file
  --request-batch-size=<value>  [default: 1000] Limit for every single request
  --source=<value>              (required) Source environment id
  --space=<value>               (required) Space id
  --target=<value>              (required) Target environment id

DESCRIPTION
  Create Entries Changeset

EXAMPLES
  $ contentful-merge create --space "<space id>" --source "<source environment id>" --target "<target environment id>" --cda-token <cda token> --output-file <output file path> --query-entries "content_type=<content_type_id>" --query-entries "sys.id=<entry_id>" --allowed-operations=add --allowed-operations=delete

contentful-merge apply

Apply Changeset

USAGE
  $ contentful-merge apply --space <value> --environment <value> --cma-token <value> [--file <value>] [--yes]

FLAGS
  --cma-token=<value>    (required) CMA token, defaults to env: $CMA_TOKEN
  --host=<value>                [default: api.contentful.com] Contentful API host
  --environment=<value>  (required) Target environment id
  --file=<value>         (required) File path to changeset file
  --space=<value>        (required) Space id
  --yes                  Skips any confirmation before applying the changeset

DESCRIPTION
  Apply Changeset

EXAMPLES
  $ contentful-merge apply  --space "<space-id>" --environment "staging" --file changeset.json

  $ contentful-merge apply  --space "<space-id>" --environment "staging" --file changeset.json --yes

contentful-merge help [COMMANDS]

Display help for contentful-merge.

Contentful CLI to diff and merge entries across environments

VERSION
  contentful-merge/0.0.0 darwin-arm64 node-v18.14.0

USAGE
  $ contentful-merge [COMMAND]

COMMANDS
  apply   Apply Changeset
  create  Create Entries Changeset
  help    Display help for contentful-merge.

Data structure

The created changeset will be saved in JSON format in a file specified with the output-file flag or if the flag is not provided in a file called changeset-[DATE]-[SPACE]-[SOURCE]-[TARGET].json. It has the following basic structure:

1{
2  "sys": {
3    "type": "Changeset",
4    "createdAt": "<date of changeset creation>",
5    "space": {
6      "sys": {
7        "id": "<space id>",
8        "linkType": "Space",
9        "type": "Link"
10      }
11    },
12    "source": {
13      "sys": {
14        "id": "<source environment id>",
15        "linkType": "Environment",
16        "type": "Link"
17      }
18    },
19    "target": {
20      "sys": {
21        "id": "<target environment id>",
22        "linkType": "Environment",
23        "type": "Link"
24      }
25    }
26  },
27  "items": [
28    // <individual changeset items, see below>
29  ]
30}

The actual changes are in the items array. They have the following structure:

1// delete
2{
3  "changeType": "delete",
4  "entity": {
5    "sys": {
6      "type": "Link",
7      "linkType": "Entry",
8      "id": "5mgMoU9aCWE88SIqSIMGYE"
9    }
10  }
11}
12
13// add
14{
15  "changeType": "add",
16  "entity": {
17    "sys": {
18      "type": "Link",
19      "linkType": "Entry",
20      "id": "5mgMoU9aCWE88SIqSIMGYE"
21    }
22  },
23  "data": {
24    // <payload of added entry>
25  }
26}
27
28// update
29{
30  "changeType": "update",
31  "entity": {
32    "sys": {
33      "type": "Link",
34      "linkType": "Entry",
35      "id": "5mgMoU9aCWE88SIqSIMGYE"
36    }
37  },
38  "patch": [
39    // <individual patch operations for each change>
40  ]
41}

There are three different change types: add, update, delete.

• Changes of type delete include changeType and entity, as seen above.

• Changes of type update include an additional property patch, with an array of patch operations where content differs between environments.

• Changes of type add include an additional property data property with the usual Contentful entry payload.

If you want to see the data structure in practice, run the create command and have a look at the generated changeset.json file, or look at the type definitions.

Limitations

At the moment we have a limit amount of entries that can be in the generated changeset

Change Type	Limit
Add	10 000
Delete	10 000
Update	10 000
Total	10 000

For apply command one can merge at most 10 000 changes at once.

Further limitations:

• Tags, Assets, Comments, Workflows and Tasks are not compared and are not copied from one environment to another.
• We only consider published entries during comparison, thus entries that are in draft state will not be compared.
• Entries when added are immediately published.
• Locales must be the same in the source and target environment.

FAQ

I have access to the environments I provided, yet the CLI responds with a 404, what could be wrong?

Make sure your CDA token has access to both environments, otherwise the CDA may respond with a 404.

I have made draft changes in my environment, but I don't see those in the changeset.

As the CDA is used to fetch and compare entries, only published changes will be taken into account. Draft changes are not available via the CDA.

Feedback

Want to report bugs, give feedback, request features?

• Found some bugs? Head over to https://support.contentful.com and open a support ticket.
• Want to request a feature or tell us your overall experience with this CLI? Feel free to use this form.

Code of Conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers. Read our full Code of Conduct here.

License

This project is licensed under MIT license.