Diff and merge content with contentful-merge

Requirements

  • A (free) Contentful account
  • Locally installed contentful-merge
  • 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 create --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>

where:

  • The file parameter expects the path to a changeset file, which can be created with the contentful-merge create command described in Compare content between environments.
  • The environment parameter 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.

Limitations

  • Changesets are created based on the Content Delivery API, therefore only published content is taken into account.

Additional resources

  • contentful-merge on github
  • The Contentful-CLI offers additional tooling to move content across spaces and environments, e.g. importing and exporting.