This guide is meant to show new users how to use the theme versioning plugin, and to answer any questions users might have. For developers, there is a section dedicated to developers who wish to write adapter plugins so that they can utilize the VCS of their choice with the UI that the Theme Versioning plugin provides.
Installation of the plugin is the same as for any other plugin. Download the plugin from the WordPress.org repository and install the plugin as usual. Alternatively, download the source and upload the template_versioning folder to your plugins directory and activate the plugin on your plugins page.
At this point, your plugin will work using the built-in version control system. However, if you are a more advanced user, and would like to use an external version control system, install the VCS Adapter plugin of your choice and activate it. Next go to the Theme Versioning Settings page and select the adapter from the drop-down menu labeled "Select a VCS" under the Adapter Settings section. Click save, and the plugin will now use the VCS you selected- it's as easy as that!
Warning: if you are not an advanced WordPress user, or don't know what a version control system is, then you probably should leave the settings as they are.
The settings page allows you to choose among the installed VCS adapters or the default VCS. Simply choose your desired VCS from the drop-down menu labeled "Select a VCS" under the Adapter Settings section.
To change between the basic mode and the advanced mode simply select your desired option from the group of buttons labeled "Choose an interface" under the Interface Settings section.
The basic interface is recommended for people who are inexperienced or forgetful users. It automatically keeps track of (commits) all changes made each time you save a file. If you have never used an actual version control system and are unfamiliar with the terms "commit" or "changeset" then this is probably the option you want to use.
The advanced interface allows the user to choose when to commit changes instead of automatically committing every time a file is saved. It allows you to commit changes to all files or just a single file. The one downside of using the advanced interface is that you will have to remember to actually click the commit button located below your theme editor text area.
There is a slight difference in how you use the plugin based on whether you choose basic or advanced mode.
In basic mode, the plugin automatically creates a revision every time you save one of your current theme files. Just edit your theme files as you always have before, and if you ever need to roll back to an earlier version, simply click the "Open Revision Viewer" button and revert your theme back to one of its previous states. For more in-depth instructions on how to use the revision viewer to revert to a previous revision see Using The Revision Viewer.
In the advanced mode, you commit revisions by clicking one of the two commit buttons below the theme editor text area. There are two different buttons: the "Commit Current File" button and the "Commit All Files" button.
The "Commit All Files" button does just that- it commits all of the theme files including the one you are currently editing. Any unsaved changes are not committed.
The "Commit Current File" button commits the current file that you are editing in the theme editor. Just as with the "Commit All Files" button, any unsaved changes are not committed.
It is very important to remember that any unsaved changes are not committed. You must save any changes that you wish to be committed before committing.
The upper section of the revision viewer entitled "Choose a Revision" allows you to choose which revision you wish to view. Select a revision and click the "View Revision" button to view the files in that revision. If you'd like, you can minimize the "Choose a Revision" section by clicking on the "+" in the upper right hand corner of the box.
The lower section of the revision viewer allows you to view the files in the revision that you have selected. The selected revision's id is indicated in bold text Where it says "Currently Viewing Revision ___". You can browse through the files in the current revision by using the drop-down menu labeled "File".
In the revision viewer, there are two ways you can roll back changes to your theme files. By clicking the "Revert Current File" button, you can revert only the currently viewed file, which will restore your that file to its state in the currently selected revision, but will leave all other files untouched. Alternatively, you can click the "Revert All Files" button, which,as its name implies, will revert all your files to the currently selected revision.
Note: Just highlighting a revision in the upper section of the revision does not select it, to select a revision you must click the "View Revision" button.
Why write an adapter plugin? If you wish to use a version control system that does not already have an adapter written, then you're out of luck... Unless you write an adapter for the VCS! After writing an adapter, you're able to use the VCS with the Theme Versioning plugin's UI.
It's actually quite simple. Implement the Theme_Versioning_VCSAdapter interface as they are described in the phpdocs and fill in all the methods to access your VCS. Next, in an activation hook, register your plugin using the theme_versioning_register_adapter function- just pass it an instance of your VCSAdapter object.
Project sponsored by Google, developed by David Julia and mentored by Ocean90 with an assist by Andrew Nacin and Daryl Koopersmith. The layout and style for this document was adapted from Mert Yazicioglu's documentation for WP Move