22. Using Version Control
The IDDE's Version Control System (VCS) allows programmers to work safely with the same source files simultaneously, integrate their changes, rebuild their own sources, and store updated master files in a common master archive.The VCS works in combination with INTERSOLV's PVCS, a popular version control program for the PC. However, VCS offers significant functional improvements over PVCS alone, because it is integrated with the IDDE's project system and has access to information stored in the project (.prj) file. Digital Mars's VCS guards against accidentally overwriting changes made by others and provides the highest level of support possible for keeping both your private project directory and the master project directory fully synchronized.
Note: If you do not have PVCS, you need to purchase it from INTERSOLV before you can use Digital Mars's VCS. See the PVCS documentation for information on PVCS features and commands.
This chapter assumes a knowledge of PVCS and a familiarity with basic version control concepts. The chapter focuses on using the group-oriented model of software development that VCS makes possible, and it explains how to use VCS to build and maintain projects.
Note: The IDDE's Version Control System (VCS) is supported only in the 16-bit version of Digital Mars C++.
Overview of VCS Concepts
This section defines basic terms used in this chapter and compares the parallel model of version control to the linear model supported by other version control systems.The next section, "Setting Up Version Control with VCS," presents an overview of how you or your project team can use VCS to establish and maintain version control on software development projects of any size.
Terminology
The following terms are used throughout this chapter:- Archive (or master archive):
- All revisions of a source file, stored in a commonly accessible directory structure, usually on a network.
- Revision:
- A revised archived source file that has a revision number and timestamp that identifies when the revision was created.
- Workfile:
- Your private copy of the revision that you are currently working on.
- Private project directory:
- Your personal working directory to which others do not have access. You work with workfiles in your private project directory.
- GET:
- The process of obtaining a private copy of a revision of an archive (usually the latest revision).
- MERGE:
- The process of collating changes to a revision into the archive, without overwriting or corrupting any changes made by others since you got the revision.
- PUT:
- The process of creating a new revision of a file in the archive.
- Version:
- A group of revisions containing all source files that make up a project. Typically you create versions to correspond to milestones in the development process, such as the weekly build or the beta build.
Version control models
There are two basic models for version control:- Linear:
- Only one person can work with a file at any one time.
- Parallel:
- Groups of people can work with the same set of files simultaneously.
Setting Up Version Control with VCS
This section gives you an overview of how you can use VCS on your software development project. The remainder of the chapter explains how to use VCS to perform the operations introduced here.Using the linear model with VCS
In the linear model, VCS locks a revision when someone GETs it; that is, VCS prevents others from making a private copy. Thus, only one person may work with a revision at a time. It is even possible to lock all revisions that make up a particular version.After changing the revision, the person who receives it must PUT it back into the master archive before others can make changes to it.
The advantage of the linear method of version control is that you do not have to collate (merge) sets of changes to a revision. The obvious disadvantage is that only one person can work on a file at a time. In large development projects in which many people are making changes to related groups of files, this model is often unworkable.
Using the parallel model with VCS
The parallel version control model allows two or more people to work simultaneously with copies of the same revision- a clear advantage even in a small work group. The disadvantage of this model is that each person's changes must be merged with changes made by others, so the master archive of a revision incorporates everyone's work and the related changes made to other files (sometimes called "dependencies").When working in a parallel version control environment, the revisions and versions used by the development team are stored in a master archive, usually on a network. Developers GET a revision (or more typically a group of related revisions) from the master archive and work with the copies (workfiles) in their own private project directory.
After making changes to a group of workfiles, developers must MERGE their changes into the latest version of revisions of the files. This is done in the private project directory because it often involves identifying changes made by others in the interim, along with resolving dependencies in other revisions that were affected by other people's changes.
Note: In your revised file, be sure to identify the revision with which you want your changes merged. You make this reference by adding a $revision entry in the file.
When changes are merged successfully, and all related changes have been made to affected revisions in the private project directory, each developer PUTs the new revisions back into the master archive.
If a revision has been modified during the MERGE, it must be remerged before it can be PUT into the archive. VCS warns you of this automatically and gives you a way to prevent other people from merging changes into the archived version of a revision until you have successfully PUT it.
The parallel model also supports branching of revisions. When you create a branch of a revision, you can PUT it back into the archive without performing a MERGE. This allows others to GET your changes to a revision. You use the branching mechanism if you want a set of changes available to you but you do not want to MERGE the changes until your work is complete. For more information, see "Creating a new branch," later in this chapter.
Setting VCS Options
This section explains how to use the options in the VCS page of the Project Settings dialog box to set up version control parameters that specify the rules VCS follows when you GET and PUT files.To open this dialog box, open the project you want to work with, and choose Settings from the IDDE's Project menu. In the Project Settings dialog box, select the VCS tab. The VCS page is shown in Figure 22-1.
[Figure 22-1 VCS page in Project Settings dialog box
Choosing a Development Model
The Development Model radio buttons specify the development model that VCS uses. Select the Parallel model, described earlier in this chapter, unless you are the only person working on the files in a project.Select Linear if you are working alone, or if you need to deny other developers access to revisions you are working on.
You can switch from the parallel to the linear mode when, for example, you need to prohibit GET operations on revisions you are merging (see "Merge Options," later in this chapter).
The IDDE sets the rest of the VCS options for you, based on the development model you select, as described later in this chapter. If you need more control over the version control process, you may change the default settings. This is not usually necessary.
Get Options
These options specify how VCS handles your requests to GET revisions from the master archive:- Get read only:
- Lets you GET files from the master archive, but with read only access; you cannot modify the files you GET. Check this option if you want to view a revision (for example, an old revision), or if you want to ensure that you do not accidentally change the files. This option is off by default in both development models.
- Get and lock:
- Prevents others from successfully executing a GET operation on a revision once you GET it. The revision remains locked until you PUT it back in the archive again. This option is on by default when you choose the Linear development model.
- Get and touch:
- Sets the time-stamp for any revision you GET to the current date and time. This setting forces recompilation of your files. It is off by default in both development models.
- Continue on overwrite error:
- Tells the IDDE to overwrite a file on a GET operation without displaying a warning. Use this setting to wipe out all changes you have made to a revision and GET a new copy from the master archives. This option is off by default in both development models.
Merge Options
The Lock Master File on Merge Setting prohibits others from executing a PUT operation on a revision in the master archive while you are performing a MERGE on it. This option is off by default in both development models.Creating a VCS Configuration File
A VCS configuration file defines a series of variables that tell VCS where to look for and create files. You can create a VCS configuration (.cfg) file with the integrated editor or any other text editor. You need a .cfg file for each project in which you use VCS.A sample configuration file, vcs.cfg, comes with Digital Mars C++. (It is installed in \dm\samples\windows\wclock by default.) The sample vcs.cfg contains information that VCS needs to work:
- vcsdir:
- The directory in which VCS stores master archives. This variable must be defined for VCS to work. (All others are optional and default to the current directory.)
- journal:
- The file name and path in which VCS creates a journal (journal.vcs) that contains the information about changes to revisions in an archive.
- archivework:
- The directory in which VCS keeps backup copies of revisions as they are updated. (This command corresponds to the LOGWORK command in older versions of PVCS.) Do not specify a RAM disk as the ARCHIVEWORK directory.
- workdir:
- The VCS temporary directory.
Selecting the configuration file
Before you use VCS for the first time on a project, you need to select the configuration file for the project:- In the Project window, choose Configuration from the
VCS menu. The Set VCS Configuration dialog box
opens.
[Figure 22-2 Set VCS Configuration dialog box
- Select the configuration file you want and click OK. You need to specify its location if it is not in the current directory.
The PVCS Registration dialog box
The first time you open the Set VCS Configuration dialog box, the PVCS Registration dialog box is displayed. You must have an INTERSOLV LAF (License Administration Facility) code to use PVCS in the IDDE. INTERSOLV supplies the LAF code to licensed users. For more information, please contact INTERSOLV. Type the code in the License Code textbox, then click OK to continue. After the PVCS Registration dialog box disappears, a message informs you that you must restart Windows.The User database directory textbox shows the database directory in which the license database is placed. This directory should be a shared directory on the network if multiple developers are using the same copy of the IDDE from the network. If developers have individual copies of the IDDE, do not change the text in this box.
Note: If you have PVCS version 5.0 or later, the IDDE does not display the PVCS Registration dialog box.
Putting Revisions into the Archive
When you PUT a revision in the master archive, VCS updates its revision number and time stamp and marks it as "not changed" with respect to the corresponding workfile in your private project directory.Note: If, while you were performing a MERGE, another person has PUT a new revision of a file you want to PUT, VCS warns you with a modal dialog box that you must perform another MERGE operation on the revision.
To prevent others from working on a revision while you are merging it, check Lock Master File on Merge. See the section "Merge Options," earlier in this chapter, for more information.
To begin a PUT operation, choose Put from the Project window's VCS menu. The Put dialog box is displayed.
[Figure 22-3 Put dialog box
The Put Candidate Files listbox shows those workfiles in your private project directory that have changed since you checked them out. Click the Add button to add files from this list to the Files to Put Back listbox; this shows the files you want to PUT into the master archive. To remove a revision from the Files to Put Back list, select it and click on Remove.
Click on Select All to select all files in the current listbox. Click on Unselect All to deselect them.
Select a file name and click on View Log for a summary of who changed the latest revision of that file and the changes that were made.
To associate comments with all selected files in the Files to Put Back listbox, type them into the Comments textbox.
Click on Put to PUT the files listed in the Files to Put Back listbox into the master archive.
Click on the Advanced button and the Put dialog box expands to show additional options.
When you PUT files into the archives, you can specify a group of files using the Put Special textboxes. The Put Special options are:
- Revision:
- Specifies the revision number you want to give the
workfiles you are putting into the archives. The revision number has
the format nn.xx, where nn is the major number and xx is the minor
number. The numbers can range from 0 to 65,535.
If you do not explicitly assign a revision number to a revision, VCS assigns one automatically by incrementing the minor number of the most recent revision by one.
- Version:
- Assigns the name you want to a group of revisions, such as beta or alpha. VCS associates the version name with all revisions listed in the Files To Put Back listbox.
- Date/Time:
- The date and time of a version or revision you archive. The default date format is mmm/dd/yy; mmm is the month, dd the day, and yy the year. The time format is hh[:mm[:ss]]; hh is the hour, mm is the minute, and ss is the second.
Creating a new branch
Use the Create New Branch option to maintain a private set of revisions in the master archives without having to MERGE them. When you have a private branch, you can change a file and perform PUT operations as often as necessary, without affecting other developers.When you are ready, you can MERGE your private revisions back into the master archive.
Note: A MERGE is the only way to make the changes in a branch available to other developers.
Getting Revisions from an Archive
Before you can work with archived revisions, you need to GET them from the archive and copy them to your private project directory using the Get dialog box, shown in Figure 22-4. (Both the archive directory and your private project directory are specified in the VCS configuration file for the project.)When you GET a revision from an archive, VCS records the revision identification numbers of the files, marks them as unchanged and not new, and adds them to your project (if you so specify in the Get dialog box).
If you are using the linear development model, VCS locks the archived revisions when you GET them so nobody else can GET them until you PUT them back. If you are using the parallel model, more than one developer can check out the revision unless you specify Get and Lock on the VCS page in the Project Settings dialog box.
To GET revisions from the master archive:
- In the Project window, choose Get from the VCS menu.
The Get dialog box is displayed.
[Figure 22-4 Get dialog box
- The VCS File Name listbox shows the names of all
revisions in the archive. Select from this list the files you
want to move to your private project directory.
To add one or more files, click on the file name(s), then click on the Add button. To add all files in the archive, click on the Select All button. VCS moves the files you select to the Work Files listbox.
To view a summary of who made certain changes to a revision, click on View Log. (This is the same log that is available from the Merge dialog box.)
- When all the files you want are in the Work Files list,
click the Get button. VCS copies those files to your
private project directory.
To remove files from the Work Files list, click on the file name(s), then click on the Remove button.
Show Archives provides the following settings:
- All archives:
- Displays all archives in the VCS File Name listbox. This is the default setting.
- New archives:
- Displays in the VCS File Name listbox the names of the new archives and archives that have changed since the last time you performed a GET operation. Choose this option to update your private copy of the project with the most current revision(s).
- Except merges:
- Displays in the VCS File Name listbox all the new
revisions in the archive except those you just merged or need to
merge. Select this option to choose only those additional archives
you need to build and to test merged revisions.
The Add Files to Project option adds the revisions automatically to the current project when VCS gets them from the archive.
To retrieve a specific revision or version, use the Get Special textboxes:
- Revision:
- is the number of the revision you want to get from the archives. The revision number has the format nn.xx, where nn is the major number and xx is the minor number.
- Version:
- is the name of the version you want to GET. The version name identifies a particular version, such as alpha or beta.
- Date/Time:
- is the date and time of a particular version or revision. The default date format is mmm/dd/yy; mmm is the month, dd the day, and yy the year. The time format is hh[:mm[:ss]]; where hh is the hour, mm is the minute, and ss is the second.
Merging Revisions
If you are working with the parallel development model, after you GET a revision and make changes to it, you may need to MERGE those changes into the master archive. The master archive presumably contains changes made by others that your revision does not include. If no other developer has changed the file, then you do not need to MERGE; you simply PUT the new revision in the master archive.Note: Remember that in your revised file, you must refer to the revision with which you want your changes merged. You do this by adding a $revision entry in the file.
When you MERGE a revision, VCS creates a backup of your revision in your private project directory. In addition, VCS provides all possible support for performing MERGE operations safely.
To merge your changes into another revision in the archive, choose Merge from the Project window's VCS menu. The Merge dialog box opens.
[Figure 22-5 Merge dialog box
The Merge dialog box contains four listboxes:
- Files you modified:
- Shows the files you modified in your private project directory since the last time you performed a GET operation.
- Files new in VCS:
- Shows archives that someone else has changed since the last time you performed a GET operation. The current (most recent) revision number is displayed. These are files you might need to GET to rebuild the project with your changes and to PUT your new revisions back into the archive.
- Files to merge:
- Shows files that both you and another person changed since the last time you performed a GET operation. These are the workfiles you need to MERGE.
- Merged files:
- Shows files that you merged during the current MERGE session.
Click the View Changes button to show the changes you need to resolve when you MERGE the selected revision. When you click View Changes, an annotated change file appears in an IDDE editor window. See the PVCS documentation for information on the format of the display and the meanings of symbols.
When you are ready to perform the MERGE operation, click on Merge. VCS guides you through a three-way merge, incorporating your changes and those made by others into a new revision.
Because the IDDE automatically makes backup copies of both the revision in your private project directory and the revision you want to MERGE it with, you can undo a MERGE (before closing the Merge dialog box) by clicking Undo Merge.
Testing the MERGE operation
To test the MERGE, return to the Get dialog box, click on Advanced, and select Except Merges. GET the files in this list and build them using the IDDE (see Chapter 8, "Testing an Application," for information).Using the VCS Manager
Use the VCS Manager for additional flexibility in managing revisions and versions. You can apply a version name to a set of archives when the software reaches a significant release step, such as beta or final release. You can also delete a named version or revision from an archive. Before deleting a version or revision, make sure that you are deleting the right one, as a deleted version or revision cannot be recovered. Finally, the VCS manager lets you lock or unlock a version or revision.To use the VCS Manager in the Project window, choose Manager from the VCS menu.
The VCS Manager dialog box shown in Figure 22-6 is displayed.
[Figure 22-6 VCS Manager dialog box
Note: You probably will not need to use the VCS Manager dialog box on most projects.
The VCS Directory listbox contains the names of revisions to add to a version or revision. Double-click on the file name to add it to the Selected Files listbox. Click on Select All to select all files.
To assign a version name, type the name, such as beta, in the Version textbox, and click on the Assign button. This assigns the version name to all files in Selected Files. The Assign and Unassign buttons are available only if you specify a version name in the Version textbox.
To control access to a particular version or revision, specify the revision (its number) or version (its name) in the appropriate textbox, then click on Lock to deny access or Unlock to allow access.
To delete a version or revision, specify the appropriate information in the Revision or Version textbox, and click on the Delete button.
Creating a Master Archive
When you begin using VCS, it may be your job to create the master archive to and from which others GET and PUT files. This section describes the process of creating a master archive.The master archive contains the revisions to all source files in a project. It also records information about changes from the previous revision, a history of the changes since the first revision, a record of who changed the files, the comments attached to the revisions as they were changed, and the date and time that each revision was PUT into the archive. See the PVCS documentation for additional information.
To set up a master archive, you PUT the workfiles in your project directory in the archives using the Put command. This command takes files from the original directory and creates the archives automatically. See "Using the VCS Manager," earlier in this chapter, for more information on the Put dialog box and how to use it.
When you PUT files in an archive, VCS changes their extensions automatically. The last character of the extension on each file is changed to V. For example, the file extension on abc.cpp becomes abc.cpv. If the file does not have an extension, VCS adds the extension .__v to the filename (two underscores and a v).
To create a master archive from the workfiles in your private project directory:
- Choose Put from the VCS menu in the Project window.
- PUT the workfiles from your private project directory
into the archive by double-clicking on the file in the Put
Candidate Files listbox.
The Put Candidate Files listbox displays the names of workfiles that you changed since the last time you performed a GET operation. The listbox also shows the files that do not yet have archives. Because you are creating the archives, all files in the project are displayed. Files you select are added to the Files To Put Back listbox.
- To add all your workfiles to the master archive, click on Select All. To remove a workfile from the list of files to archive, select the file in the Files To Put Back list and click on the Remove button.
- Optional: Type a comment in the Comments textbox. VCS applies your comment to all selected files in the Files to Put Back listbox.
- Click the Put button to create the master archives and PUT your workfiles in them.