Diff and merge content with contentful-merge
Table of Contents
- What is contentful-merge?
- Diff content between environments
- Merge content between environments
- Further resources
- A (free) Contentful account
- Locally installed
- The environments to compare must have identical content models. (Sync content models with help of the Merge App or the merge commands of Contentful-CLI
- A CDA and a CMA token with access granted to all environments to compare.
What is contentful-merge?
The contentful-merge CLI tool allows you to diff 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.
Diff content between environments
To diff content between environments, run the following command:
contentful-merge --cda-token <cdaToken> --space <spaceId> --source <sourceEnvironmentId> --target <targetEnvironmentId>
This returns an output that informs you about all added, updated and deleted entries:
Start changeset creation for staging => new-campaign-content 🎬 ✔ Creating a Changeset [1s] ✔ Check content model [0.6s] ✔ Entries [0.9s] ✔ Reading the source environment "staging" [0.2s] ✔ Reading the target environment "new-campaign-content" [0.2s] ✔ Counting number of entries changes between environments [0.0s] ✔ Fetching full payload for 3 entries to be compared [0.2s] ✔ Checking for diverged content types [0.0s] ✔ Fetching full payload for 2 added entries [0.1s] Changeset successfully created 🎉 ✔ 198 entries detected in the source environment "staging" ✔ 196 entries detected in the target environment "new-campaign-content" ✔ 2 added entries ✔ 1 updated entry ✔ 0 deleted entries 💾 /home/janko/contentful/contentful-merge/changeset-1699447071346-aqxl7objo13l-staging-new-campaign-content.json 📖 /home/janko/contentful/contentful-merge/log-create-changeset-1699447071348.log
To see a more detailed overview of all changes, view the newly created changeset file which holds all relevant information in a machine-readable JSON format.
Merge content between environments
To merge content between environments, run the following command:
contentful-merge apply --cma-token <cmaToken> --space <spaceId> --environment <environmentId> --file <changesetFilePath>
fileparameter expects the path to a changeset file, which can be created with the
contentful-mergecreate command described in Compare content between environments.
environmentparameter expects the ID of the environment you want to apply the changeset to.
After confirming, the following output is returned:
Start applying changeset to new-campaign-content 📥 ✔ Applying the Changeset [3s] ✔ Load changeset data [0.0s] ✔ Validating changeset [0.5s] ✔ Deleting 0 entries [0.0s] ✔ Adding 2/2 entries [1s] ✔ Updating 1/1 entries [1s] Changeset successfully applied 🎉 ✔ 3 changes applied in the environment "new-campaign-content" ✔ 2 added entries ✔ 1 updated entry ✔ 0 deleted entries 📖 /home/janko/contentful/contentful-merge/log-apply-changeset-1699447148704.log
Now the content of both of your environments is in sync.
- Changesets are created based on the Content Delivery API, therefore only published content is taken into account.