Compare and Merge Branches using the CLI

Note: The Branches Compare and Merge feature is currently released as part of an Early Access program and may not be available to all users.

Contentstack provides Branches to create multiple copies of your stack content. By default, stacks have a main branch. You can fork a branch from the main branch (parent branch) to create a new branch (child branch).

Contentstack lets you list, create, delete, compare, and merge Branches using the Command-line Interface. You can compare two branches and merge the two with the desired changes into a single branch.

This step-by-step guides you on how to create, update, delete, compare, and merge Branches using the CLI. In CLI, base branch is the source branch, and compare branch is the target branch.

Prerequisites

1. Contentstack account
2. CLI installed and configured (version 1.7.0 and above)  
3. CLI authenticated
4. Branches enabled for your organization

Note: Please contact your organization administrator for more details.

Steps to List, Create, and Delete Branches

You can list the branches in a stack, create a new branch in a stack from a base branch, and delete an existing branch from a stack.

List Branches

1. Open a terminal.
2. Enter the following command to list down the available branches:
csdx cm:branches

3. You will be prompted to enter a Stack API key. To list the branches of a specific stack, enter its Stack API key.

   You can see the branches for the specific stack displayed.

Alternatively, you can pass the Stack API key in the command as given below:

csdx cm:branches --stack-api-key <value>

You can also view the list in a detailed view using the verbose flag:

csdx cm:branches --verbose

Usage

csdx cm:branches

or

csdx cm:branches -k <value>

or

csdx cm:branches --stack-api-key <value>

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• --verbose=verbose: Verbose, display information in detailed format.

Create a Branch

1. Open a terminal.
2. Enter the following command to create a new branch:
csdx cm:branches:create

3. Enter the Stack API key of the stack for which you want to create a branch.
4. Enter a source branch for the branch you want to create.
5. Enter a unique ID (name) for branch UID.

You have successfully created a new branch.

Alternatively, you can pass the Stack API key, source, and UID in the command as given below:

csdx cm:branches:create --stack-api-key <value> --source <value> --uid <value>

Limitations

• The branch UID must be in lower case, and only ‘_’ can be used to separate two words.
• The maximum character length for a branch UID is 15.
• The maximum number of branches allowed per stack depends on the product tier.
• Once you create a branch, you cannot edit its name or the source branch.

Usage

csdx cm:branches:create

or

csdx cm:branches:create --stack-api-key <value> --source <value> --uid <value>

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• --source=source: Source branch from which a new branch is to be created.
• --uid=uid: Branch UID (unique name) to be created.

Delete a Branch

1. Open a terminal.
2. Enter the following command to delete a branch:
csdx cm:branches:delete

3. Enter the Stack API key of the stack from which you want to delete a branch.
4. Enter the UID of the branch you want to delete.
5. To confirm the deletion, you will be prompted to type the name of the branch you want to delete.

You have successfully deleted a branch.

Alternatively, you can pass the Stack API key and UID in the command as given below, and then in the following step, on prompt, enter the name of the branch to confirm the deletion.

csdx cm:branches:delete --stack-api-key <value> --uid <value>

To forcefully delete a branch by bypassing the confirmation step, pass the command as given below:

csdx cm:branches:delete --stack-api-key <value> --uid <value> --yes

Usage

csdx cm:branches:delete

or

csdx cm:branches:delete --stack-api-key <value> --uid <value>

or

csdx cm:branches:delete --stack-api-key <value> --uid <value> --yes

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• --uid=uid: Branch UID to be created.
• -y, --yes: Force the deletion of the branch by skipping the confirmation.

Examples

• To list out the branches in a stack
csdx cm:branches --stack-api-key bltxxxxxxxx7

• To create a new branch in a stack
csdx cm:branches:create --stack-api-key bltxxxxxxxx7 --source test1 --uid test2

• To delete a branch from a stack
csdx cm:branches:delete --stack-api-key bltxxxxxxxx7 --uid test2

Steps to Configure Base Branches

You can set, get, or remove the default base branch for a stack. This will be used as the default base branch when performing a compare or merge command.

Set

1. Enter the following command to set a base branch:
csdx config:set:base-branch

2. Enter the Stack API key of the stack where you want to set the base branch.
3. Enter the name of the branch you want to set as the base branch.

Alternatively, you can pass the Stack API key and branch name in the command as given below:

csdx config:set:base-branch --stack-api-key <value> --base-branch <value>

Usage

csdx config:set:base-branch

or

csdx config:set:base-branch --stack-api-key <value> --base-branch <value>

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• --base-branch=base-branch: Base branch.

Get

1. Enter the following command to get the base branch:
csdx config:get:base-branch

The base branch will be displayed along with the Stack API key.

Usage

csdx config:get:base-branch

Remove

1. Enter the following command to remove a base branch:
csdx config:remove:base-branch

2. Enter the Stack API key of the stack for which you want to remove the base branch.
3. On prompt, enter Y to remove the base branch.

Alternatively, you can pass the Stack API key in the command as given below, and then on prompt, enter Y to remove the base branch.

csdx config:remove:base-branch --stack-api-key <value>

To forcefully remove the base branch by bypassing the confirmation step, pass the command as given below:

csdx config:remove:base-branch --stack-api-key <value> --yes

Usage

csdx config:remove:base-branch

or

csdx config:remove:base-branch --stack-api-key <value>

or

csdx config:remove:base-branch --stack-api-key <value> --yes

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• -y, --yes: Force remove.

Examples

• To set a base branch in a stack
csdx config:set:base-branch --stack-api-key bltxxxxxxxx7 --base-branch test2

• To remove the base branch from a stack
csdx config:remove:base-branch --stack-api-key bltxxxxxxxx7 --yes

Steps to Compare Branches

Follow the steps below to compare two branches:

1. Enter the following command to compare two branches:
csdx cm:branches:diff

2. Enter the Stack API key of the stack where you want to compare the branches.
3. Enter the name of the compare branch.
4. You will be prompted to choose a module. You can choose a specific module or all modules to compare. Choose the module of the branch you want to compare.

Alternatively, you can pass the Stack API key, base branch (source branch), and compare branch (target branch) in the command as given below:

csdx cm:branches:diff --stack-api-key <value> --base-branch <value> --compare-branch <value> --module <value>

Note: If you want to choose a different base branch other than the default one, you must specify the flag for the base branch as given in the command above.

You will get the comparison results as displayed below: 



This displays the branch comparison summary along with the modules affected.

5. Pass the format flag as given below to get detailed branch comparison results.
csdx cm:branches:diff --stack-api-key <value> --base-branch <value> --compare-branch <value> --format detailed-text

You will get the detailed comparison results as displayed below: 



This displays the branch comparison summary and the modules along with the affected sub-modules. In our example, the content types are displayed along with their fields.

The comparison results are distinguished based on the following:

• A “+” symbol with green highlighted text: Indicates that this is present only in the compare branch.
• A “±” symbol with blue highlighted text: Indicates that this is present in both branches, but has different values between them.
• A “-” symbol with red highlighted text: Indicates that this is not present in the compare branch.

Usage

csdx cm:branches:diff

or

csdx cm:branches:diff --stack-api-key <value> --base-branch <value> --compare-branch <value> --module <value>

or

csdx cm:branches:diff --stack-api-key <value> --base-branch <value> --compare-branch <value> --module <value> --format <value>

Options

• --base-branch=base-branch: Base branch.
• --compare-branch=compare-branch: Compare branch.
• -k, --stack-api-key=stack-api-key: Provide the Stack API key to show the difference between branches.
• --module=module: ['content-types', 'global-fields', 'all'].
• --format=format: [Optional] Type of flags to show difference between two branches. ['compact-text', 'detailed-text']

Examples

• To compare the content types between two branches
csdx cm:branches:diff --stack-api-key "bltxxxxxxxx" --base-branch "main" --compare-branch "develop" --module "content-types"

• To compare the global fields between two branches with format
csdx cm:branches:diff --stack-api-key "bltxxxxxxxx" --base-branch "main" --compare-branch "develop" --module "global-fields" --format "detailed-text"

Steps to Merge Branches

Follow the steps below to merge two branches:

1. Enter the following command to merge two branches:
csdx cm:branches:merge

2. Enter the Stack API key of the stack where you want to merge the branches.
3. Enter the name of the compare branch. By default, the current base branch will be automatically used.

Alternatively, you can pass the Stack API key, base branch, and compare branch in the command as given below:

csdx cm:branches:merge --stack-api-key <value> --base-branch <value> --compare-branch <value>

Note: If you want to choose a different base branch other than the default one, you must specify the flag for base branch as given in the command above.

The branches' compare results will be displayed for individual modules as Content Types Summary and Global Fields Summary.

4. Choose a merge strategy from the displayed list.
   • Merge, Prefer Base: Adds all changes from the compare branch to the base branch. In case of any conflicts, the preference goes to the base branch.
   • Merge, Prefer Compare: Adds all changes from the compare branch to the base branch. In case of any conflicts, the preference goes to the compare branch.
   • Merge, Ask for Preference: Asks you to choose how you want to merge every difference individually at the content type or global field level.
   • Overwrite with Compare: Replaces the base branch with the compare branch. Anything in the base branch that is not in the compare branch is removed.

   The following table contains an example of field changes to a content type between the base branch and compare branch, and explains how the changes are merged based on the merge strategy you choose:

   Base Branch	Compare Branch	Merge, Prefer Base	Merge, Prefer Compare	Overwrite with Compare	Is conflict?
   Title (unchanged)	Title (unchanged)	Title (unchanged)	Title (unchanged)	Title (unchanged)	No
   Categories (present)	(not present)	Categories (from Base)	Categories (from Base)		No
   Feature B (renamed/reconfigured)	Feature C (renamed/reconfigured)	Feature B (from Base)	Feature C (from Compare)	Feature C (from Compare)	Yes
   (not present)	SEO Description (present)	SEO Description (from Compare)	SEO Description (from Compare)	SEO Description (from Compare)	No
   Topics		Topics (from Base)	Topics (from Base)	(removed from Base)	No

5. If you choose Merge, Prefer Base or Merge, Prefer Compare from step 4, choose what you want to merge from the following list:
   • New in Compare Only: Adds only new items from the compare branch to the base branch. All the items that are modified are ignored.
   • Modified Only: Adds only modified items from the compare branch to the base branch. All the items that are new are ignored.
   • Both: Adds both new and modified items from the compare branch to the base branch.
   • Go Back: Takes you back to the previous step.
   • Start Over: Takes you back to step 4.

   The following table contains the content types in the base branch and compare branch, explaining how data is merged based on the merge strategy preference you choose:

   Base Branch	Compare Branch	Merge New in Compare Only	Merge Modified Only, Prefer Base	Merge, Modified Only, Prefer Compare
   Title	Title	Title	Title	Title
   Categories		Categories	Categories	Categories
   Feature B	Feature C	Feature B	Feature B	Feature C
   	SEO Description		SEO Description	SEO Description
   Topics		Topics	Topics

6. If you choose Overwrite with Compare from step 4, or New in Compare Only, Modified Only, or Both from step 5, choose what you want to do next from the following list:
   • Export merge summary: Exports the merge result summary to the specified location but does not execute the merge action. This can be used to apply the merge later.
   • Execute merge: Executes the merge action and exports the merge result summary to the specified location.
   • Go Back: Takes you back to the previous step.
   • Start Over: Takes you back to step 4.
7. If you choose Merge, Ask for Preference, follow the steps below:
   1. Select the content type changes for merge from the provided tabular column. With this, you can choose to modify/add/remove only those content types from a selected branch during the merge operation. 
   

   Note: If you want to ignore the changes in the compare branch for a specific content type, select the Ignore(Use Base) option for that content type.

   Tip: Use the arrow keys to move along the table cells and then hit the spacebar to make the selection.

   2. Select the global field changes for merge from the provided tabular column. With this, you can choose to modify/add/remove only those global fields from a selected branch during the merge operation.
   

   Note: If you want to ignore the changes in the compare branch for a specific global field, select the Ignore(Use Base) option for that global field.

   3. In the next step, choose what you want to merge from the following list:
      • Export merge summary: Exports the merge result summary to the specified location but does not execute the merge action.
      • Execute merge: Executes the merge action and exports the merge result summary to the specified location.
      • Go Back: Takes you back to the previous step.
      • Start Over: Takes you back to step 4.

With this, the merge operation is completed, and the Entry Migration files generated are placed in the “YYYYMMDDHHMMSS_bltxxx” folder under merge_scripts folder in the current working directory.

Usage

csdx cm:branches:merge

or

csdx cm:branches:merge --stack-api-key <value> --base-branch <value> --compare-branch <value>

Options

• -k, --stack-api-key=stack-api-key: Stack API key.
• --base-branch=base-branch: Base Branch.
• --compare-branch=compare-branch: Compare branch.
• --comment=comment: Pass a comment.
• --export-summary-path=export-summary-path: Export summary file path.
• --use-merge-summary=use-merge-summary: Path of merge summary file.
• --no-revert=no-revert: If passed, will not create the new revert branch.

Examples

• To merge feature-branch with the base branch for a stack.
csdx cm:branches:merge --stack-api-key bltxxxxxxxx --compare-branch feature-branch

• To merge branches and export the results summary to a file path.
csdx cm:branches:merge --export-summary-path file/path