Introduction | Features | Installation | Usage | Commands | Data structure | FAQ | Feedback | Code of Conduct | License
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.
- 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.
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.changedAtproperty of all entries present in both environments. Subsequently, for all entries with distinctsys.changedAtvalues, a more comprehensive comparison of their payload is performed. If any variations are found, a patch is generated to reflect the differences.
💡 Want to merge content types instead of entries? 💡 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.
Prerequisite: node v18
npm install -g contentful-merge$ npm install -g contentful-merge
$ contentful-merge COMMAND
running command...
$ contentful-merge (--version)
contentful-merge/0.0.0 darwin-arm64 node-v20.2.0
$ contentful-merge --help [COMMAND]
USAGE
$ contentful-merge COMMAND
...Create Entries Changeset
USAGE
$ contentful-merge create --space <value> --source <value> --target <value> --cda-token <value> [--request-batch-size <value>] [--output-file <value>]
FLAGS
--cda-token=<value> (required) CDA token, defaults to env: $CDA_TOKEN
--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>
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
--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
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.
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:
{
"sys": {
"type": "Changeset",
"createdAt": "<date of changeset creation>",
"space": {
"sys": {
"id": "<space id>",
"linkType": "Space",
"type": "Link"
}
},
"source": {
"sys": {
"id": "<source environment id>",
"linkType": "Environment",
"type": "Link"
}
},
"target": {
"sys": {
"id": "<target environment id>",
"linkType": "Environment",
"type": "Link"
}
}
},
"items": [
// <individual changeset items, see below>
]
}The actual changes are in the items array. They have the following structure:
// delete
{
"changeType": "delete",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
}
}
// add
{
"changeType": "add",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
},
"data": {
// <payload of added entry>
}
}
// update
{
"changeType": "update",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
},
"patch": [
// <individual patch operations for each change>
]
}There are three different change types: add, update, delete.
-
Changes of type
deleteincludechangeTypeandentity, as seen above. -
Changes of type
updateinclude an additional propertypatch, with an array of patch operations where content differs between environments. -
Changes of type
addinclude an additional propertydataproperty 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.
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.
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.
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.
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.
This project is licensed under MIT license.