Developer Blog

Content Versioning Pre-Release Details

Published August 23rd, 2023

Written By

Esther Agbaje

Developer Advocate

With Thanks To

Kevin Lewis

Pascal Jufer

TagsUpdate

You can now use Content Versioning in the pre-release version of Directus to provide valuable feedback that will shape this feature.

Content versioning follows a git-like workflow: you have a main version of an item, and then can create branches, add content to those branches, and finally incorporate (or 'merge') those changes back into the main version.

This unlocks two powerful new authoring workflows - preparing draft updates of content without publishing them, and collaboration with others without accidentally overwriting content.

Please note that Content Versioning is in our new pre-release version, and shouldn't be used in production as we finalize the feature based on feedback. Things may change or break! We're also still writing proper documentation - so what we have in the meantime is all here in this post.

To try the Content Versioning pre-release, use our new beta release. For our docker image it would be directus/directus:10.7-beta or directus/directus:beta.

Feedback Wanted ​

We want to hear your thoughts - please drop by the #content-versioning channel in our Discord server and share your views. We're interested in all feedback, but one thing we're struggling with is terminology given that not all Directus Data Studio users are devs: branches, committing, merging, and 'main' as the default branch are terms all up for grabs.

Quickstart Guide on Content Versioning ​

Content versioning is enabled in a collection's data model settings, with each item having its own set of branches. Content Versioning exists in addition to our existing Revisions feature, which is still available on a per-branch basis.

Create a New Branch ​

1. Go to the collection that has content versioning enabled.
2. Add content to your collection. By default, content is saved in the main branch.
3. Edit the content. You should now see the option to create a new branch.
4. Click on the "Create New Branch" button and give your branch a name.
5. Click "Save " to create the new branch.

Commit to a Branch ​

1. Select the branch you want to add content to.
2. Modify the content you want to include in this branch.
3. Click the "Commit" button to save.

Merge Branch ​

1. Select the branch you want to merge changes from.
2. Click on the "Merge Current branch" from the dropdown.
3. Confirm the changes by merging.

Using Branches with Live Preview ​

You can use the Branch variable in your Live Preview URL. Combine this with your frontend, and preview all of your branches directly within Directus.

Content Versioning via API ​

This is a non-exhaustive list of endpoints related to Content Versioning. By the time we fully release the feature, they will be fully documented in our API reference.

Branch Object ​

{
	"id": "21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5",
	"name": "My Branch",
	"collection": "my-collection",
	"item": "1",
	"hash": "aaafc0db8fb60e82e634903523e1fa2144c58520",
	"date_created": "2023-08-23T10:38:20.686Z",
	"user_created": "a2dbc923-7c75-4d26-83f4-4674bfa7be81"
}

{
	"id": "21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5",
	"name": "My Branch",
	"collection": "my-collection",
	"item": "1",
	"hash": "aaafc0db8fb60e82e634903523e1fa2144c58520",
	"date_created": "2023-08-23T10:38:20.686Z",
	"user_created": "a2dbc923-7c75-4d26-83f4-4674bfa7be81"
}

Read Branches ​

GET /branches to show all branches that exist in Directus.

GET /branches/:id to show a specific branch.

Create Branch ​

POST /branch with a branch object:

{
	"name": "My Branch",
	"collection": "my-collection",
	"item": "1"
}

{
	"name": "My Branch",
	"collection": "my-collection",
	"item": "1"
}

Read Branch Content ​

/items/:collection/:id?branch=branch_name

You must URL-encode branch names (a space becomes %20, for example). If a branch does not exist, or no branch is provided, we will fallback to the main branch. Commit to a Branch POST /branches/:id/commit with an object containing fields you are updating. For example:

{
	"my_field": "updated value"
}

{
	"my_field": "updated value"
}

Merge Branch ​

Merging branches takes two steps - comparing, and merging.

GET /branches/:id/compare will return a mainHash and any fields which differ from the main branch:

{
    "outdated": false,
    "mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
    "current": {
      "my_field": "updated value"
    },
    "main": {
      "my_field": "main value"
    }
}

{
    "outdated": false,
    "mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
    "current": {
      "my_field": "updated value"
    },
    "main": {
      "my_field": "main value"
    }
}

POST /branches/:id/merge will take any provided fields and overwrites the value in the main branch:

{
	"mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
	"fields": [ "my_field" ]
}

{
	"mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
	"fields": [ "my_field" ]
}

Delete Branch ​

When you're done with a branch, delete it. Branches are not deleted automatically once merged.

DELETE /branches/:id

New Action & Filter Event ​

Content Versioning also introduces a new action and filter event that is exposed to Hooks and Flow Triggers: items.merge.

We Hope You Like It! ​

We have been working hard on Content Versioning as a tool to support complex authoring workflows. Please drop by the #content-versioning channel in our Discord server and share your views.