Merge
Merge
A merge copies the changes in a compare branch into a base branch, by the merge strategy you choose. Use this class to
- merge a branch into the base branch
- list the recent merge jobs of the stack
- read the status of one merge job
stack.branch("<BRANCH>").mergeQueue() returns a Merge with <BRANCH> as the base branch. Merge has no public constructor.
| Name | Type | Description |
|---|---|---|
| branchUid | String | UID of the base branch. Pass it to stack.branch() before you call mergeQueue(). |
- Known issue: In 1.16.0, a Merge object does not carry the api_key and authorization headers of the stack, so its requests reach the API without credentials. Add both with addHeader on the Merge object, as every example on this page does.
addHeader
addHeader adds one request header to this merge object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header. |
| value (required) | String | Value of the header. |
Returns: Merge. The same merge object, for chaining.
Validation
- There is no client-side validation. A null key or value does not throw here.
- execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a header map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addHeader stores the header in the header map of this object and sends nothing.
- A later call with the same name replaces the value.
- The header goes on every request of this merge object: branch, find, and fetch, and stays there for every later request.
- A new Merge object holds only a Content-Type header. It does not carry the api_key and authorization headers of the stack, so add them with this method before you send a request.
Example
Basic usage: add the stack credentials and list merge jobs
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListMergeJobs {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
// The Merge object does not inherit the stack credentials
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>");
Response<ResponseBody> response = merge.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds every entry of a map to the request headers of this merge object.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap | Header names mapped to their values. |
Returns: Merge. The same merge object, for chaining.
Validation
- Throws NullPointerException if headers is null, because addHeaders copies every entry of the map.
- execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a header map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addHeaders copies the entries into the header map of this object and sends nothing.
- An entry replaces a header with the same name.
- The headers go on every request of this merge object: branch, find, and fetch, and stay there for every later request.
- A new Merge object holds only a Content-Type header. It does not carry the api_key and authorization headers of the stack, so add them with this method before you send a request.
Example
Basic usage: add the stack credentials from a map
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class ListMergeJobsWithHeaderMap {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("api_key", "<API_KEY>");
headers.put("authorization", "<MANAGEMENT_TOKEN>");
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeaders(headers);
Response<ResponseBody> response = merge.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to this merge object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter, sent as its string form. |
Returns: Merge. The same merge object, for chaining.
Validation
- There is no client-side validation. A null key or value does not throw here.
- execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a query map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addParam stores the pair in the query parameter map of this object and sends nothing.
- A later call with the same key replaces the value.
- The parameter goes on every request of this merge object: branch, find, and fetch.
- The parameter stays on the object for every later request.
- The map already holds base_branch, the UID of the branch you called mergeQueue() on. A base_branch key that you add replaces it.
Example
Basic usage: merge into a different base branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class MergeIntoDevelopment {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>")
// Replaces base_branch "main", which mergeQueue() set
.addParam("base_branch", "development");
Response<ResponseBody> response = merge
.branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into development")
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
addParams adds every entry of a map to the query parameters of this merge object.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap | Query parameter names mapped to their values. |
Returns: Merge. The same merge object, for chaining.
Validation
- Throws NullPointerException if params is null, because addParams copies every entry of the map.
- execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a query map.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addParams copies the entries into the query parameter map of this object and sends nothing.
- An entry replaces a parameter with the same name.
- The parameters go on every request of this merge object: branch, find, and fetch.
- The parameters stay on the object for every later request.
- The map already holds base_branch, the UID of the branch you called mergeQueue() on. A base_branch key that you add replaces it.
Example
Basic usage: set the base branch from a map
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class MergeWithParamMap {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("base_branch", "development");
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>")
.addParams(params);
Response<ResponseBody> response = merge
.branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into development")
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}branch
branch builds the request that merges the compare branch you name into the base branch of this Merge, by the merge strategy you choose.
| Name | Type | Description |
|---|---|---|
| compareBranch (required) | String | UID of the branch whose changes you merge. |
| requestBody (required) | JSONObject | Request body. Pass an empty object when you need no per-item strategy. |
| requestBody.item_merge_strategies | List<JSONObject> | Overrides the default strategy for specific content types or global fields. |
| defaultMergeStrategy (required) | String | Merge strategy for every item, for example merge_prefer_base. |
| mergeComment (required) | String | Comment that the merge shows. |
Returns: Call<ResponseBody>. The request that merges the compare branch into the base branch, sent when you call execute().
Validation
- There is no client-side validation of the four arguments.
- execute() throws IllegalArgumentException if requestBody is null, because Retrofit cannot build a request without a body. It throws the same exception if compareBranch, defaultMergeStrategy, or mergeComment is null, because Retrofit rejects null entries in a query map.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Merge branches request (POST /stacks/branches_merge) with requestBody as the JSON body.
- branch puts compare_branch, default_merge_strategy, and merge_comment into the query parameters of this object, beside base_branch. The values stay on the object, so later find and fetch requests send them too.
- The API reference lists the following seven values for defaultMergeStrategy:
- merge_prefer_base: merges the compare branch into the base branch and keeps the base branch changes on a conflict.
- merge_prefer_compare: merges the compare branch into the base branch and keeps the compare branch changes on a conflict.
- overwrite_with_compare: replaces the base branch with the compare branch and discards changes that are not in the compare branch.
- merge_new_only: adds only new items from the compare branch and ignores modified items.
- merge_modified_only_prefer_base: merges only modified items and keeps the base branch changes on a conflict.
- merge_modified_only_prefer_compare: merges only modified items and keeps the compare branch changes on a conflict.
- ignore: merges nothing directly. Pass item_merge_strategies in the body to choose a strategy per item.
- The merge covers content types and global fields only.
- The API responds with a merge job and its status before the merge finishes. Read the job with fetch.
Example
Basic usage: merge a branch into main, preferring main on conflicts
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class MergeBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// The Merge object does not inherit the stack credentials, so add them here
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>");
Response<ResponseBody> response = merge
.branch("docs-test-branch", new JSONObject(), "merge_prefer_base", "Merge docs-test-branch into main")
.execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: choose a strategy per content type
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
import java.util.Collections;
public class MergeBranchPerItem {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>");
// With the "ignore" default, only the listed items merge
JSONObject item = new JSONObject();
item.put("uid", "<CONTENT_TYPE_UID>");
item.put("type", "content_type");
item.put("merge_strategy", "merge_prefer_compare");
JSONObject body = new JSONObject();
body.put("item_merge_strategies", Collections.singletonList(item));
Response<ResponseBody> response = merge
.branch("docs-test-branch", body, "ignore", "Merge one content type from docs-test-branch")
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}fetch
fetch builds the request that reads the status and configuration of one merge job.
| Name | Type | Description |
|---|---|---|
| mergeJobUid (required) | String | UID of the merge job to read. |
Returns: Call<ResponseBody>. The request for the merge job, sent when you call execute().
Validation
- There is no client-side validation of mergeJobUid.
- execute() throws IllegalArgumentException if mergeJobUid is null, because Retrofit cannot fill the request path with null.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get single merge job request (GET /stacks/branches_queue/{merge_job_uid}) with the headers and query parameters of this object.
- The response of branch carries the UID of the merge job it started.
Example
Basic usage: read the status of a merge job
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchMergeJob {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// The Merge object does not inherit the stack credentials, so add them here
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>");
Response<ResponseBody> response = merge.fetch("<JOB_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}find
find builds the request that lists the recent merge jobs of the stack.
Returns: Call<ResponseBody>. The request for the recent merge jobs, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all merge jobs request (GET /stacks/branches_queue) with the headers and query parameters of this object.
- The query parameters always include base_branch, and the values from an earlier branch call on the same object. The API reference lists no query parameters for this request.
- The API returns the last 100 merge jobs by default.
Example
Basic usage: list the recent merge jobs
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Merge;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListMergeJobs {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// The Merge object does not inherit the stack credentials, so add them here
Merge merge = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.branch("main")
.mergeQueue()
.addHeader("api_key", "<API_KEY>")
.addHeader("authorization", "<MANAGEMENT_TOKEN>");
Response<ResponseBody> response = merge.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}