> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Diff and merge content with contentful-merge

> This guide explains how to diff and merge content across environments with contentful-merge

## Requirements

* A (free) [Contentful account](https://www.contentful.com/sign-up/)
* Locally [installed](https://github.com/contentful/contentful-merge#installation) `contentful-merge`
* The environments to compare must have identical content models. (Sync
  content models with help of the [Merge App](https://www.contentful.com/marketplace/app/merge/) or the merge commands of [Contentful-CLI](/tutorials/cli/merge-app-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:

```bash
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:

```bash
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:

```bash
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](#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:

```bash
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](/references/content-delivery-api/overview),
  therefore only published content is taken into account.

## Additional resources

* `contentful-merge` on [github](https://github.com/contentful/contentful-merge)
* The [Contentful-CLI](/tools/cli) offers additional tooling to move content across
  spaces and environments, e.g. importing and exporting.

> This guide explains how to diff and merge content across environments with contentful-merge