---
title: "Changeset"
description: "Discover how Cloud CMS manages changesets to track your content revisions and ensure seamless branch editing. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/reference/types/changeset"
---

# <a id="top"></a>Changeset

An Object

1.  [Platform](/documentation/gitana/4.0/reference/types/platform.md)
2.  [Repository](/documentation/gitana/4.0/reference/types/repository.md)
3.  [Changeset](/documentation/gitana/4.0/reference/types/changeset.md)

##### Table of Contents

- [Overview](#top "Overview")
- [Parent](#parent "Parent")
- [Properties](#properties "Properties")
- [Methods](#methods "Methods")
- [Schema](#schema "Schema")

Cloud CMS automatically creates and maintains the state of the individual changesets that compose your branches as you work with content. A changeset is like a transparency for a visual projector. When you write content into a branch (via a create, update or delete), the content is written onto a changeset (or transparency). That way, the things you worked on before are never affected. The new updates are just overlaid on top.

In this sense, a branch can be thought of as a stack of changesets. There is a root changeset (where the branch starts) and a tip changeset (where the branch ends). Everything in-between constitutes the changeset history of the branch.  
  
This portion of the API therefore is largely for advanced users. The Cloud CMS API lets you dig in and poke around at the changeset history of branches to do things like discover what changes were introduced on which changeset in the branch.  
  
You probably don't need to do this unless you're building some really cool authoring or curation tools. Cloud CMS provides applications out-of-the-box that hopefully let you do most of the heavy lifting from an authoring viewpoint. So most of these APIs are cool but probably not very commonly used.

## Changeset IDs

Most of the `_doc` identifiers for objects inside of Cloud CMS are GUIDs (globally unique IDs). Changesets are a bit different. Changeset IDs are stored in the `_doc` field but they have a special structure which looks like this:

`{revision}:{guid}`

As you write nodes into your branch, new changesets are layered into the branch. One at a time. Each new changeset has an incremented revision and a brand new GUID. Thus, the revision number always goes up one integer at a time. The changeset ID ends up looking something like this: `452:4b5b685c980c10f98beb`

## Transactions

Changesets play an important role in transaction handling for writes onto branches. When a transaction begins, a new changeset is created. All of the writes (creates, updates and deletes) which occur as part of the transaction are committed to the database and flagged with the changeset. Only once all the writes have succeeded is the changeset flipped to an 'active' state.  
  
If a transaction fails, the changeset is not flipped to an 'active' state. Instead, the transaction rolls back and the database state is cleaned up.  
  
Only one changeset in a branch can be written to at a time. Thus, if a transaction is started and another thread running in your application attempts to write to the branch, it will be blocked and forced to wait until the first thread completes.

> **Note:** Drop in one of our language drivers to accelerate your development.  
> Here are links to some of our popular [Cookbooks](/documentation/gitana/4.0/developers/cookbooks/overview.md) to help you get started!
> 
> - [C#](/documentation/gitana/4.0/developers/cookbooks/csharp.md)
> - [Go](/documentation/gitana/4.0/developers/cookbooks/go.md)
> - [Java](/documentation/gitana/4.0/developers/cookbooks/java.md)
> - [JavaScript](/documentation/gitana/4.0/developers/cookbooks/javascript2.md)
> - [PHP](/documentation/gitana/4.0/developers/cookbooks/php.md)
> - [Python](/documentation/gitana/4.0/developers/cookbooks/python.md)
> - [Ruby](/documentation/gitana/4.0/developers/cookbooks/ruby.md)

## <a id="parent"></a>Parent

This Changeset is contained within a [Repository](/documentation/gitana/4.0/reference/types/repository.md).

## <a id="properties"></a>Properties

The following properties are available:

| Property | Type | Default | Read-Only | Description |
| --- | --- | --- | --- | --- |
| \_doc | string |  | No | The primary ID |
| \_system | object |  | No | Metadata maintained by the system |

## <a id="methods"></a>Methods

The following methods are available:

- [Export Changeset](#post-repositories-repositoryid-changesets-changesetid-export "Export Changeset")
- [Forks Changesets](#get-repositories-repositoryid-changesets-forks "Forks Changesets")
- [Heads Changesets](#get-repositories-repositoryid-changesets-heads "Heads Changesets")
- [Import Changeset](#post-repositories-repositoryid-changesets-changesetid-import "Import Changeset")
- [Joins Changesets](#get-repositories-repositoryid-changesets-joins "Joins Changesets")
- [List Nodes](#get-repositories-repositoryid-changesets-changesetid-nodes "List Nodes")
- [List Parents](#get-repositories-repositoryid-changesets-changesetid-parents "List Parents")
- [Lists Changeset](#get-repositories-repositoryid-changesets "Lists Changeset")
- [Queries for Changeset](#post-repositories-repositoryid-changesets-query "Queries for Changeset")
- [Read Changeset](#get-repositories-repositoryid-changesets-changesetid "Read Changeset")
- [Read Children Changeset](#get-repositories-repositoryid-changesets-changesetid-children "Read Children Changeset")
- [Read Node](#get-repositories-repositoryid-changesets-changesetid-nodes-nodeid "Read Node")
- [Root Changesets](#get-repositories-repositoryid-changesets-root "Root Changesets")
- [Update Changeset](#put-repositories-repositoryid-changesets-changesetid "Update Changeset")
- [Update Changeset](#post-repositories-repositoryid-changesets-changesetid-update "Update Changeset")

### <a id="post-repositories-repositoryid-changesets-changesetid-export"></a>Export Changeset

Starts an export job for this resource

POST /repositories/{repositoryId}/changesets/{changesetId}/export

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |
| groupId | false | string | The Group ID to be assigned to the exported archive |
| artifactId | false | string | The Artifact ID to be assigned to the exported archive |
| versionId | false | string | The Version ID to be assigned to the exported archive |
| vaultId | false | string | The ID of the vault where the exported archive should be saved |
| schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') |

#### Response

```json
{
  "type": "object",
  "description": "Export Configuration",
  "properties": {
    "startDate": {
      "type": "object",
      "description": "Only include objects whose modification date is after this time (epoch millis). This is used for partial or rolling exports."
    },
    "endDate": {
      "type": "object",
      "description": "Only include objects whose modification date is before this time (epoch millis). This is used for partial or rolling exports."
    },
    "startChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or beyond the specified changeset."
    },
    "endChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or before the specified changeset."
    },
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during export."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during export."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during export."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during export."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during export."
    },
    "artifactDependencies": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "artifactIncludes": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "forceIncludes": {
      "type": "boolean"
    }
  }
}
```

### <a id="get-repositories-repositoryid-changesets-forks"></a>Forks Changesets

GET /repositories/{repositoryId}/changesets/forks

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |

### <a id="get-repositories-repositoryid-changesets-heads"></a>Heads Changesets

GET /repositories/{repositoryId}/changesets/heads

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |

### <a id="post-repositories-repositoryid-changesets-changesetid-import"></a>Import Changeset

Starts an import job for this resource

POST /repositories/{repositoryId}/changesets/{changesetId}/import

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |
| groupId | false | string | The Group ID to be assigned to the exported archive |
| artifactId | false | string | The Artifact ID to be assigned to the exported archive |
| versionId | false | string | The Version ID to be assigned to the exported archive |
| vaultId | false | string | The ID of the vault where the exported archive should be saved |
| schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') |

#### Response

```json
{
  "type": "object",
  "description": "Import Configuration",
  "properties": {
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during import."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during import."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during import."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during import."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during import."
    },
    "strategy": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": "CLONE",
      "description": "Either CLONE or COPY_EVERYTHING. Use CLONE to keep the same IDs on import. Use COPY_EVERYTHING to generate all new IDs for all entries on every import."
    },
    "substitutions": {
      "type": "string"
    }
  }
}
```

### <a id="get-repositories-repositoryid-changesets-joins"></a>Joins Changesets

GET /repositories/{repositoryId}/changesets/joins

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |

### <a id="get-repositories-repositoryid-changesets-changesetid-nodes"></a>List Nodes

GET /repositories/{repositoryId}/changesets/{changesetId}/nodes

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

### <a id="get-repositories-repositoryid-changesets-changesetid-parents"></a>List Parents

GET /repositories/{repositoryId}/changesets/{changesetId}/parents

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

### <a id="get-repositories-repositoryid-changesets"></a>Lists Changeset

Retrieves a list of Changeset instances

GET /repositories/{repositoryId}/changesets

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| sort | false | object | Defines how to sort fields in the result set |
| skip | false | number | Skips the result set cursor ahead the specified number of records |
| limit | false | number | Specifies the number of records to be handed back in the result set |

This method supports pagination.

#### Response

```json
{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_changeset"
      }
    }
  }
}
```

### <a id="post-repositories-repositoryid-changesets-query"></a>Queries for Changeset

Queries for instances of type Changeset

POST /repositories/{repositoryId}/changesets/query

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| sort | false | object | Defines how to sort fields in the result set |
| skip | false | number | Skips the result set cursor ahead the specified number of records |
| limit | false | number | Specifies the number of records to be handed back in the result set |

This method supports pagination.

#### Response

```json
{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_changeset"
      }
    }
  }
}
```

### <a id="get-repositories-repositoryid-changesets-changesetid"></a>Read Changeset

Reads an instance of a Changeset

GET /repositories/{repositoryId}/changesets/{changesetId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

#### Response

```json
{
  "type": "object",
  "extends": "document",
  "description": "Changeset",
  "container": "repository",
  "properties": {
    "_doc": null,
    "_system": null
  }
}
```

### <a id="get-repositories-repositoryid-changesets-changesetid-children"></a>Read Children Changeset

GET /repositories/{repositoryId}/changesets/{changesetId}/children

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

### <a id="get-repositories-repositoryid-changesets-changesetid-nodes-nodeid"></a>Read Node

GET /repositories/{repositoryId}/changesets/{changesetId}/nodes/{nodeId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |
| nodeId | true | string | The ID of the node |

### <a id="get-repositories-repositoryid-changesets-root"></a>Root Changesets

GET /repositories/{repositoryId}/changesets/root

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |

### <a id="put-repositories-repositoryid-changesets-changesetid"></a>Update Changeset

PUT /repositories/{repositoryId}/changesets/{changesetId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

### <a id="post-repositories-repositoryid-changesets-changesetid-update"></a>Update Changeset

Updates an existing Changeset

POST /repositories/{repositoryId}/changesets/{changesetId}/update

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| repositoryId | true | string | The ID of the repository |
| changesetId | true | string | The ID of the changeset |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

## <a id="schema"></a>Schema

```json

{
  "type": "object",
  "extends": "document",
  "description": "Changeset",
  "container": "repository",
  "properties": {
    "_doc": null,
    "_system": null
  },
  "id": "changeset"
}
```
