GenHelm supports a feature that allows you to save and restore backup versions of all of your specifications in order to facilitate recovery of a previous version of your work. There are two methods by which a specification can be archived.
In this help we describe these options, as well as the process of reverting back to an archived version and deleting archives.
Archives are versions of previous XML specifications. No actual code is ever archived since the code can always be recreated from the specifications. Archives are saved as zip files within each site's private_data archive directory. Each zip file contains all archived versions of a single specification.
Whenever you are editing a specification, you can request that an archive be taken by entering the "archive" command, followed by a description of the archive. Usually the description should reflect the current state of the specification so that you will be able to identify this version later. For example, let's say you are about to embark on a major enhancement involving updates to a payment class to incorporate Google Pay. It is a good idea to capture the state of the class before you make your changes in case you ever need to back out your updates and return to a "known good" state. You might begin by creating an archive using the command:
archive Before Google Pay support
The very first archive command for a specification cannot be made until after the specification has been saved (at least once) since the archive command uses the name of the current specification to determine the name of the archive file and this name is not known unless and until the specification has been saved or stowed. The archive command captures the state of the specification as it exists within the editor. Therefore, it is possible to take several archives between stow operations.
In addition to On Demand archives, it is possible to configure sites to take automatic archives each time a specification is saved or stowed. This is done by setting the Auto Archive flag when stowing the site's generation_options model. The automatic archives are built into GenHelm's stow and save commands. When enabled, a snapshot of the previously saved specification will be taken automatically, prior to saving the current specification. Enabling automatic archives is a good idea for mission-critical sites where it may be necessary to go back to a previously saved version of a specification.
A few models don't participate in the Automatic Archive feature since they don't tend to generate components for which historical archives are necessary. This includes the following models:
On Demand and Automatic archiving is not mutually exclusive. In fact, it is recommended that On Demand archives be taken in certain situations, even when capturing Automatic Archives. This is because:
The "restore" command is used to load a previously archived specification into the editor. Although this command won't affect what has been saved, it will replace any unsaved work in progress. Therefore, if you have made changes to the current specification that you wish to keep, be sure to save this before restoring another version. In order to restore a previous version you must pass a version identifier to the restore command. Often you will want to use the restore command without a parameter first, in order to see a list of available archives like the one below.
To replace the current contents of the editor with the contents of an archived version you must pass a reference number to the restore command. Positive references are relative to the oldest archive while negative references are relative to the most recent archive. For example, if you want the latest archived version use the command:
restore -1
To load the second most recent archive use the command:
restore -2
If you want to restore the oldest archived version, use the command:
restore 1
Referring to the list above, the parameter passed to restore one of the 6 available archives would need to be from -6 to 6 (excluding 0).
Over time, the number of archives will steadily increase and will take up more and more disk space. Therefore, it is a good idea to delete old archive versions that are unlikely to be needed in the future. The "dearchive" command is used to delete archive versions. There are several different forms of dearchive parameters as described below.
In order to delete a singe archive version, pass the number of the archive to be deleted. Only positive numbers can be used. These coincide with the positive version numbers from column one of the archive list shown above.
To delete a range of archive versions, pass the first and the last version within the range. For example, to delete the oldest, second oldest and third oldest archive versions, enter the command:
delete 1:3
Use an asterisk to delete all archive versions.
You can add auto to the parameter list to limit the deletions to only Automatic Archives created during save and stow processing. For example, to delete all automatically saved archives without deleting any On Demand archives, use the command:
dearchive * auto
When you delete a specification, its archive is not deleted by default. However, if an archive file exists you will be shown a warning message such as the yellow message below.
If you don't want to preserve the archive your next command should be:
dearchive *
This will delete the archive associated with the specification you just deleted.
If you decide not to delete the archive at this time, and you want to delete it later, you will need to first create a specification using the same name. Then you can delete the archive for this specification and then delete the specification also. Alternatively, you can delete the archive using File Manager or FTP utilities that can access the site's archive folder.