Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/contentful/contentful-merge

CLI to merge entries between environments
https://github.com/contentful/contentful-merge

cli contentful

Last synced: 11 days ago
JSON representation

CLI to merge entries between environments

Host: GitHub
URL: https://github.com/contentful/contentful-merge
Owner: contentful
License: mit
Created: 2022-11-01T06:32:40.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2025-01-16T03:13:15.000Z (19 days ago)
Last Synced: 2025-01-17T04:07:40.719Z (18 days ago)
Topics: cli, contentful
Language: TypeScript
Homepage:
Size: 4.96 MB
Stars: 21
Watchers: 11
Forks: 7
Open Issues: 20
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

Contentful Merge

## Introduction

**Contentful**

[Contentful](https://www.contentful.com/) 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.

![](images/recording.gif)

### 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](src/analytics/index.ts) data.
- We would love your feedback! [Here](https://forms.gle/uVj4sG2jKmQHotRd6) 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](https://www.contentful.com/developers/docs/references/content-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](https://www.contentful.com/marketplace/app/merge/) to your space, or, if you prefer the command line, check out the [Merge CLI](https://github.com/contentful/contentful-cli/tree/master/docs/merge).

## Installation

Prerequisite: node v18

```bash
npm install -g contentful-merge
```

## Usage

```sh-session
$ 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
...
```

## Commands

- [`contentful-merge create`](#contentful-merge-create)
- [`contentful-merge apply`](#contentful-merge-apply)
- [`contentful-merge help [COMMANDS]`](#contentful-merge-help-commands)

#### `contentful-merge create`

```
Create Entries Changeset

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

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

DESCRIPTION
Create Entries Changeset

EXAMPLES
$ contentful-merge create --space "" --source "" --target "" --cda-token --output-file --query-entries "content_type=" --query-entries "sys.id=" --allowed-operations=add --allowed-operations=delete
```

#### `contentful-merge apply`

```
Apply Changeset

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

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

DESCRIPTION
Apply Changeset

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

$ contentful-merge apply --space "" --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:

```javascript
{
"sys": {
"type": "Changeset",
"createdAt": "",
"space": {
"sys": {
"id": "",
"linkType": "Space",
"type": "Link"
}
},
"source": {
"sys": {
"id": "",
"linkType": "Environment",
"type": "Link"
}
},
"target": {
"sys": {
"id": "",
"linkType": "Environment",
"type": "Link"
}
}
},
"items": [
//
]
}
```

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

```javascript
// delete
{
"changeType": "delete",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
}
}

// add
{
"changeType": "add",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
},
"data": {
//
}
}

// update
{
"changeType": "update",
"entity": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "5mgMoU9aCWE88SIqSIMGYE"
}
},
"patch": [
//
]
}
```

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](src/engine/types.ts).

## Limitations

At the moment we have a [limit amount](./src/config.base.ts#L2) 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](https://forms.gle/uVj4sG2jKmQHotRd6).

## 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](https://www.contentful.com/developers/code-of-conduct/) here.

## License

This project is licensed under [MIT license](LICENSE).