Version Control is one of the basics when developing code. It allows you to track and manage changes to your code (and associated files) ... you can 'turn back the clock' and revert to an earlier version of your code ... or you can view the changes that have been made since an earlier point in time.
The standard VBE doesn't include any support for version control (I know ... you can export and import a Module ... but that's not "version control"!) so I decided to add it with VBE_Extras.
The following provides a brief summary of Version Control. Before using it for the first time, you may want to read the Version Control section of the VBE_Extras user guide which provides further details.
Note that Version Control comes in two 'types':
"Full" - exports to / imports from a 'timestamped' folder so creating a new folder for each export and allowing import from any of those folders. Use this option if you want to export / import on your local device and / or want to have multiple exports available. An XML file is included with each export which includes the date/time of the export and, optionally, a ‘reason’ (that you specify during the export process) and your username. When performing an import, this information will be shown to you to aid in selecting the correct export to be imported.
"Plain" - exports to / imports from one specific folder. When you perform an export, any existing export files in the folder will be deleted. Use this option if using an 'external' Version Control system e.g. Git (but note that VBE_Extras' Version Control does not integrate directly with Git or any other version control tool, rather it creates / updates the files/folder that you can then 'commit').
If you're wondering which to use: if you are familiar with Git or other 'external' Version Control systems and want to integrate with them, use "Plain" Version Control ... otherwise use "Full" Version Control. The remainder of this post assumes you are using "Full" Version Control.
Exporting
Before you can import anything with Version Control, you need to export something - either your entire VBA Project or an individual Module (Version Control works at both the Project and Module level ... and if you export a Project you can subsequently import individual Modules if you want).
The Version Control menu is controlled via the Project Window ... right-click on the name of the Project to export your entire Project or right-click on the name of a Module to export an individual Module. Then select Extras > Version Control and Export Project or Export Module as appropriate.
Depending on which host application you are using, whether you are exporting the entire VBA Project or a single Module, the type of Module(s) being exported and other factors, you may be shown a dialog or two providing further information. You will then be asked to provide a 'reason' for the export: this is a brief piece of text describing why you are creating an export. This text will be shown to you when subsequently doing an import and so assists you with selecting the correct version if you have created multiple exports.
You'll then be shown a dialog confirming the export was completed or detailing any problems.
Importing
At a later point in time when, possibly, you want to revert to an earlier version of your code (for the entire Project if you exported the Project or for an individual Module) you can then perform an import.
Again, the Version Control menu is controlled via the Project Window ... right-click on the name of the Project to import your entire Project or right-click on the name of a Module to import an individual Module. Then select Extras > Version Control and:
Import Project (add and update Modules) ... available when importing the entire Project
Import Project (replace Modules) ... available when importing the entire Project ... the difference to the above option is that (as well as adding and updating Modules), this will remove Modules that are currently in your VBA Project but that are not in the version you are now importing
Import this Module ... available when importing an individual Module
Import new Module ... available via the import Project or import Module menu items
Note that having made this selection, no import will immediately take place.
First, if you have previously created more than one export, you will be asked which one of those exports you want to import (to help you, you will be shown the date and time of each previous export and, unless you have de-selected the relevant options in the Settings, the username of the user that created the export and the reason for the export).
Then, VBE_Extras determines the differences between your existing code (in the Project in the VBE) and the previously exported version and shows you a 'diff report' dialog detailing those differences.
If you have selected to import an individual Module then you be shown the Module-level diff report ... see below.
If you have selected to import the entire Project (whether 'add and update Modules' or 'replace Modules') then you will first be shown a Project-level diff report listing each Module within the Project that has differences ... it could be that if you proceed with the import then the Module will be updated, or the Module might be deleted or that a Module might be added.
Project-level diff report
So that's pretty handy ... being able to see which Modules will be impacted by the import. But what if you wanted to know, for the Modules that will be added or deleted, what the code is (for those that will be deleted) or was (for those that will be added)? Simple, select the Module in the report then click the View button (or just double-click the Module) and you will be shown the code in a new dialog window.
Module-level diff report
Possibly more importantly, what if you wanted to know, for the Modules that will be updated, what those updates would be at a more granular level? Simple ... in the Project-level diff report, select the Module and click View or double-click the Module and you will be shown the Module-level diff report listing each procedure and property (and the 'declaration lines' if they will also be updated ... I'm going to refer to each of these as 'members' for the rest of this post ... I appreciate that the 'declaration lines' are not a member ... but it's a lot less typing) within the Module that has differences ... it could be that if you proceed with the import then the members will be updated, deleted or added (or, of course, it might be that specific members had no changes in which case they will not be listed).
So, again, that's pretty handy ... being able to see which members will be impacted by the import. But what if you wanted to know, for the members that will be added or deleted, what the code is (for those that will be deleted) or was (for those that will be added)? Simple, select the member in the Module-level diff report then click the View button (or just double-click the member) and you will be shown the code in a new dialog window.
Member-level diff report
Again, possibly more importantly, what if you wanted to know, for the members that will be updated, what those updates would be at the line-by-line level and character-by-character level? Simple ... select the member in the Module-level diff report and click View or double-click the member and you will be shown the member-level diff report with those differences highlighted:
Green - for insertions (will only appear in the upper text box representing the version of the text in the VBE that is being 'compared from')
Red - for deletions (will only appear in the lower text box representing the version of the text in the selected file that is being 'compared to')
Yellow - for changes other than change of case ... i.e. a combination of a deletion and an insertion (so will appear in both the upper and lower text boxes)
Blue - for change of case only (so will appear in the upper and lower text boxes)
So that's pretty handy!
You can then go back to the Project-level diff report (or Module-level diff report, if importing an individual Module) dialog and click Import to let VBE_Extras do the import for you.
Anything else to know?
Some key things to know are:
As well as exporting / importing your VBA code (in all types of Modules), Version Control includes:
Exporting / importing Attributes in Standard, Class and UserForm Modules (not sure what Attributes are? ... read my VBA Attributes post)
Exporting / importing UI elements (Controls etc) in UserForms
When exporting / importing the entire Project, Version Control will also identify differences and, optionally, update Project References (i.e. references that your VBA Project has to Type Libraries and to other VBA Projects ... to read more about Project References and TypeLibs see my Adding / updating "Project References" in the VBE post).
In Excel, Word and PowerPoint: when exporting / importing the entire Project, Version Control will also identify differences in the Project's RibbonX (if you're not sure what RibbonX is, see my Adding a Button (and a ComboBox) to the Ribbon post) though it will not update the RibbonX during an import (this is because it cannot be updated ... the file containing the RibbonX is, obviously, open and so its internal "customUI" file cannot be updated).
And in Access, in addition to the above:
UI elements in Forms and Reports
Attributes in Forms and Reports
Version Control allows export / import to and from one of 3 specific locations:
Project folder - always exports to and imports from the same folder that the VBA Project (e.g. the Excel Workbook, the Access Database etc) is in.
Project sub-folder - always exports to and imports from a sub-folder of the of the folder that the VBA Project (e.g. the Excel Workbook, the Access Database etc) is in - that folder will be named the same as the Excel Workbook, the Access Database etc.
Specific folder - always exports to the same folder for all VBA Projects but allows you to set (and change) that folder each time you perform an export or import.
Various settings (including which of the '3 locations' to use; whether to save the username and/or 'reason' to the XML file) are available in the Version Control tab of VBE_Extras' Settings dialog (in the main menu, select Extras > Settings > Version Control).
And for everything else you might want to know about VBE_Extras and Version Control, read the VBE_Extras user guide.
Comments