Was this article helpful?
Thanks for your feedback
The branches feature in Contentstack allows you to create multiple copies of your stack. You can add numerous branches of your stack and migrate your content to these branches.
Branches primarily help you sync between your code and content model without making significant changes to the code.
Additional Resource: See our detailed documentation on Branches in Contentstack and understand how branches are helpful in real-world scenarios.
Using the Contentstack CLI's Migration plugin, you can migrate your content from one branch to another using a migration script.
Additional Resource: We recommend you to refer to our extensive guide on migration plugin and how to write a migration script for your content or refer our GitHub page.
In this guide, let's look at different possible use case scenarios where you can use the CLI migration plugin to migrate your content from one branch to another.
Here are a few possible scenarios where you can use the migration plugin to migrate your content.
Let's understand each use case in detail.
Note: We assume you are well versed with the migration script and migration plugin. If not, read our detailed documentation on how to get started with the migration script and use the migration plugin to migrate your content.
Rename/ Remove a Field in your Content Type (Minor Change)
Consider a scenario where you want to apply a minor change to your content type. In this example, let's understand how to rename/ remove a field in your content type using branches.
To do this, follow the steps given below:
- Create a develop branch from your main (production) branch for your stack to store the updated content.
- Now, add the following tasks in your migration script to perform the respective operations:
- Begin by adding a task to create a new field with the latest (updated) field name in your content type.
- Write tasks to add the data and update the entries with the newly created field.
Warning: We recommend you to keep the existing fields and optionally delete the old fields after your latest changes are published live. This will help you easily roll-back, in case the new changes are not as expected.
Additional Resource: We recommend you check some example scripts on our GitHub page. This will help you get started with the tasks mentioned above.
- Now, check your script, finalize the content and add a task to publish it.
- You can move to your UI and make appropriate changes to the UI. Make other suitable changes at your end and start using the newly created field.
- Content editors can verify the changes and content managers can confirm the changes on the develop (test) branch.
- Use the migration plugin command given below to apply your changes to the main branch.
csdx cm:migration -A -n <file_path> -k <api_key> -b <branch_name>
Note: Make sure, while running the script, it should point to the target branch.
While deploying, remember to deploy the migration script first and then deploy the UI.
Update Content Models (Major Change)
This is a complex use case where you want to make some significant changes to your stack. While revamping your website's content models or restructuring your application, you have to include some major updates to your stack.
Consider an example where you want to update the content models of your stack. Let's see the steps involved in executing this example using branches:
- Begin by creating a branch from the main (production) branch of your stack, where the new models will be stored.
- Then, update the migration script and write custom tasks to modify the existing content models according to the new changes.
Add the following tasks to your migration script to perform the respective operations:- Begin by creating tasks to update the content models.
- Add tasks to update the entries according to the new content models by adding your data to these entries.
- Once all the changes are done, add a task to your migration script to publish the changes.
Additional Resource: We recommend you check some example scripts on our GitHub page. This will help you get started with the tasks mentioned above.
- Now you can move to the UI and make appropriate changes. You can also make other suitable changes at your end.
- After applying the changes, content editors can verify the changes and content managers can confirm the changes on the develop (test) branch.
- Use the following migration plugin command to migrate your content to the newly created release branch.
csdx cm:migration -A -n <file_path> -k <api_key> -b <branch_name>
Note: Make sure, while running the script, it should point to the target branch.
- Finally, you can deploy all the changes on your production branch. This can be done in the following two ways:
- Use an alias for release: This is an efficient way to apply new changes to your existing content. To use this method, create a production alias that points to the release branch.
Additional Resource: Read our detailed guide on how to use aliases in content branching.
Note: By using an alias for release, you can eliminate the risk of data loss. In case of any errors, it will by default rollback to the old code/ branch.
- Merge all your changes with the main branch: You can easily merge your content from the release branch to the main branch. This can help you merge data with the main branch and apply the changes.
Note: We recommend you to use this method only if your changes are minimal and can be easily merged with the main branch.
- Use an alias for release: This is an efficient way to apply new changes to your existing content. To use this method, create a production alias that points to the release branch.
- While deploying, remember to deploy the migration script first and then deploy the UI.
- If your changes are working properly after deployment, you can merge them into your main branch. This will help you to keep a single original branch.
Additional Resource: We highly recommend you to check our GitHub page for more information on migration script creation, use cases, and advanced examples.
