Version Control Strategies documentation for the dotCMS Content Management System

You may use many different types of content and code in your dotCMS implementation. Although all of this content is stored and may be managed within dotCMS, you may wish to store and manage some portions of your dotCMS content separately, such as in a Source Code Control System (sccs) or an online code repository such as GitHub.

This document describes many of the most common methods used to access and manage dotCMS content and code from external systems, and integrate dotCMS content into existing development processes.


  • HTML
  • Velocity
  • Javascript


Themes, Templates, Containers, Pages, Widgets


Import and Export Content API

Best Practices

1. Abstract all externally referenced content into files

The #dotParse() and #dotInclude() commands enable you to include the contents of a Velocity or text file in almost any type of dotCMS content, including but not limited to Themes, Templates, Containers, Pages, Widgets, and individual content items. These commands enable you to abstract the components of your dotCMS content and pages into files, which can then be easily managed remotely via WebDAV or the REST API.

For example, if you wish to track and manage your Container code in an external SCCS, you can encapsulate the code for each Content Type a Container supports into a separate file (stored in the dotCMS browser tree), and then the only code in the actual Container object will be a single #dotParse() command in the section for each Content Type which references the appropriate file. You can then manage all the Containter code externally from dotCMS, including editing, checking in and out, versioning, and other standard source code control operations, without having to change any code within dotCMS.

2. Add version information to file metadata

Whenever you upload or update a file in dotCMS, the metadata is automatically extracted and added to the file object within dotCMS, where it is accessible both in the file properties and via Velocity code. So if you maintain version information about files in a separate system, you can link that version information into dotCMS by simply writing the version into the file metadata before uploading it into dotCMS.

3. Control back-end access

To ensure that changes are made within your normal (external) process, you should set your dotCMS Permissions to limit access as much as possible to the back-end editing interface and/or to the content items that your code is being included in (via your externally managed code files).

4. Automate updates to your included code files