[Home]
[Contents]
[Prev]
[Next]
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.
Most version control systems support a linear model of version
control. In practice, few support a parallel version control system
because additional support is required to prevent losing changes.
The Digital Mars C++ IDDE, however, fully supports the parallel model.
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 \sc\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.
It is a good idea to give the .cfg file for a project the same name as
the project itself and to save it in your private project 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.
Click on the Advanced button to display the following additional
options: Show Archives, Get Special, and Add Files to Project.
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.
To display a log showing who changed an archive and what changes
were made at each revision, click on a file name in one of the
listboxes and click on the View Log button. See the PVCS
documentation for information on the display format.
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.