Source Control Plugins Overview

A HotDocs Author plugin is a piece of software you can add to your HotDocs Author directory to enhance Author's abilities in a given area. To enable you to keep track of the various versions of each template you create, HotDocs Author provides an optional source control plugin.

Using a source control system enables you to track the history of edits you make to a template, share the template development role with other template authors on your team, and keep a repository of your template files.

About Source Control

A source control system provides a file repository for your templates and tracks their change histories. The file repository is either centralized on a server, or distributed across the computers of all those using the repository. When you want to edit a file, you "check out" a local copy of that file to the relevant workspace so you can make the changes you want to the template.

After you finish editing your template, you "check in" the changes you made to your local copy. This updates the repository version of the template so that the repository now has a new version of the original file. This enables you to retrieve previous versions of the template if needed. The version control software also keeps a record of who edits the template file. This enables you to know the proper person to talk to about any concerns you may have about changes to a given version of the template.

There are two main types of source control systems:

  • Centralized source control: The file repository is stored on a server and users must check out and check in files from this central location to their local computer.
  • Distributed source control: The file repository exists on every user's computer and file changes update in all locations at once.

Basic Concepts

There a few basic aspects to using a source control system:

Check Out a Template

Before editing a source controlled template, you must first check out the template. That means you are creating a local copy of the file repository version of the template so you can make changes without actually affecting the repository copy until you are completely happy with your edits and purposefully check them in to the repository.

Get the Latest Version of a File

With a source controlled system, you are always working on a copy of the main repository file. To avoid making changes that conflict with another user's changes, you need to keep your copy of the file up to date with the main file stored on the server. Getting the latest version of the file downloads to your machine any edits that another user has checked in to the repository since the last time you updated. It is best practice to always get the latest version of your local copy of a file before you start making edits.

Check a Template into the Repository

Once you are happy with the edits you have made to a checked out file, you need to upload your changes to the repository version of the file.. This is called checking in. When you check in, the repository overwrites the repository version of your template with your edits and this becomes the primary version that other users can checkout.

Undo a Check Out

If you have checked out a file and made an edit you are unhappy with, you can "revert" the file, or undo the checkout. Reverting a file returns it to the state it was in when you checked it out of the repository and does not apply any changes to the repository version of the file.

View History

The successive versions of the individual templates the repository contains are called revisions. Each revision has a unique identification number attached to it. This unique identification number enables the repository to keep a history of the template's revisions. You can use revisions to view the "change history" of a file, seeing who has edited it and what changes they made. You can also roll back a file to a previous revision. This means making an older version of the file the primary file that users can checkout and edit. This may be useful if you made an error in a later revision, or if you want to branch your file history into two parallel template versions that both start from the same revision but are then edited differently so you can create two separate templates from one.

Source Control Plugins for HotDocs Author

Using a source control plugin with HotDocs Author enables you to perform source control functions from within the workspace. Once you have linked a workspace to your source control repository, you can use the workspace interface itself to update, check in, check out, and revert template files. Adding the plugins to Author alters the workspace interface to add new options and new menu items to carry out these tasks.

The currently available source control plugins include: