Content Versioning

Content versioning allows teams to create and manage different versions of their content. There are several reasons to use content versioning, including drafting content without publishing it, and more ways to collaborate effectively.

Concepts

• Version: a version of an item is a snapshot that gets copied from the current or main version, allowing you to safely make changes and later promote to be the main version. Any changes to the main version made in the meantime are updated automatically.
• Main: the main version is the original version of a piece of content that has been created. It is the default version that is displayed to users. The main version is the "source of truth" for all other versions. This is often used for published content.
• Promote: promoting a version means to make it the new main version. When a new version is promoted, it becomes the main version that is displayed to users, and it replaces the previous main version.
• Revision: revisions are individual changes to items made within a version or the main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.

Setting Up Content Versioning

Navigate to Settings > Data Model, select the collection that you want to enable content versioning for, and scroll down to the content versioning section. Toggle "Enable Versions" and save your data model.

Creating a New Version

Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.

Making Changes to a Version

Open the item in the newly created version, and make the desired edits to the item's content.

Upon saving the changes, you'll notice that the main version remains unaffected, while the changes are reflected only in the modified version.

Comparing and Promoting a Version

Promoting a version makes it the main (current) version of your content.

How to Promote a Version

1. Open the version you want to promote
2. Select the "Promote Version" option from the dropdown.
3. In the comparison modal, review the changes:
   • Fields with differences from the main version are highlighted with color indicators
   • Review each highlighted field to understand what will change
4. Accept or reject individual changes as needed
5. Click "Promote" to finalize and make this version the new main version

Once promoted, this version becomes the active content, and the previous main version is preserved in the version history.

After promoting a version, you can choose to keep or delete the version.

Revisions and Content Versioning

Under the hood, revisions are stored in the directus_revisions collection. In bigger projects this collection can get large.

Managing Revision Retention

You can manage revision retention in two ways:

• Automatic Retention Policies: Configure environment variables to automatically control how long revisions are kept. This allows you to balance the need for historical data with storage and performance considerations. See the Log Retention documentation for configuration options.
• Manual Cleanup: Periodically remove some or all data from the directus_revisions collection. Note that manual deletion may unintentionally remove content versions that are still in use, so exercise caution when performing bulk deletions.

When implementing retention policies, consider your team's workflow and how far back you may need to revert changes before removing older revisions.

Viewing and Restoring Revisions

You can view revisions for an item within the right sidebar of the Studio. How many fields were updated in each revision is clarified via the label e.g. "Updated 2 Fields".

Upon selecting a revision, you will see the differences between the current main version (indicated on the left) and that revision (indicated on the right).

The 'Updated' label indicators demonstrate which fields were updated in that revision, and the change indicators assist in understanding how that data currently compares to main.

To restore a revision, select "Apply" from within the revision comparison modal.