with assistance from Bob. Ventimiglia (http://www.bobev.com/)
This section describes how the SCM patterns in this book map to the concepts imple-mented by several commonly used software version control (VC) tools. The intent is
TABLE 1-1. Some Commonly Used Version Control Tools
Tool Vendor Web Site
VSS - Visual Source Safe Microsoft http://msdn.microsoft.com/ssafe/
CVS - the Concurrent
Versions System
CVS is Open Source - develop-ment is hosted by Collab.Net
http://www.cvshome.org/
Perforce Perforce Software http://www.perforce.com/
BitKeeper BitMover Inc. http://www.bitkeeper.com/
AccuRev AccuRev Inc. http://www.accurev.com/
not to give the operational details for a “cookbook” or “HowTo” but to instead refer to the tool-specific mechanisms, and how they work together to support our SCM patterns. This should provide a conceptual base for looking up detailed usage instructions in the product documentation.
For each tool, its basic concepts and terminology are briefly described in order to pro-vide a high-level overview of how to use it to perform the following common activi-ties:
• Create a PRIVATE WORKSPACE (6)
• Configure and populate it from a REPOSITORY (7) or from a codeline
• Create a change-task and/or a TASK BRANCH (19)
• Update the workspace with the latest state of the codeline
• Perform a TASK LEVEL COMMIT (11) of the changes from the workspace into the codeline
• Create a new codeline (for a MAINLINE (4), an ACTIVE DEVELOPMENT LINE (5), a RELEASE LINE (17), a RELEASE-PREP CODE LINE (18), or a THIRD PARTY CODELINE
(10))
• Create a label or version-identifier for one of the NAMED STABLE BASES (20)
ClearCase Rational Software http://www.rational.com/products/clearcase/
UCM - Unified Change
Management Rational Software http://www.rational.com/products/clearcase/
CM Synergy Telelogic http://www.telelogic.com/products/synergy/
StarTeam Starbase http://www.starbase.com/products/starteam/
PVCS Dimensions Merant PVCS http://www.merant.com/pvcs
PVCS Version Manager Merant PVCS http://www.merant.com/pvcs MKS Integrity MKS Inc. http://www.mks.com/products/sie/
TABLE 1-1. Some Commonly Used Version Control Tools
Tool Vendor Web Site
VSS - Visual Source Safe
VSS is one of the more commonly used VC tools among those using a
Microsoft-based integrated development environment (IDE) such as Visual C++. Although it has a nice GUI and very seamless integration with the programming language envi-ronment, VSS is among the less capable tools described here. VSS has relatively lim-ited support for branching and parallel development. It is not intended for projects which regularly require multiple codelines.
A repository in VSS corresponds to a database which holds one or more master projects. VSS supports “project-oriented” operations that operate on all selected files, or all the files defined to be in a specified project. A master project is simply a VSS project which holds the master copies of a set of files and their latest versions (it also serves as the mainline).
A development workspace is created in VSS by associating a project with a working directory.
The working directory is populated by performing a project-oriented get operation to retrieve the latest versions of a project’s files into the working directory for read-only access. A checkout operation is used to copy a writable copy of a file into the working directory.
The working directory may be updated with the latest project versions by doing another get project operation from the master (or codeline) project into the working directory.
TABLE 1-2. Mapping of SCM pattern concepts to VSS concepts
SCM Pattern concept
name VSS concept name Comments
Repository master project
Development Workspace working directory
Codeline share & branch see also “pin”
Change Task N/A
Workspace Update get project from the master/codeline project into the working directory
Task-level Commit checkin project
Task Branch N/A
Label label project
Changes from the working directory may be “committed” to the codeline by doing a checkin project operation from the working directory into the master (or codeline) project where the latest versions of the project are stored for that codeline.
VSS doesn’t have a separate notion of a change-task, it relies upon project operations in the working directory to be performed in task order. And since branching in VSS is limited, branches are almost never created for the purpose of a single task.
A new codeline is created for a project by “sharing and branching” the files in that project to create a new copy of that project:
• The share operation (formerly called “pin”) links and copies the selected file versions from the master project into a new project for the new codeline.
• The branch operation makes sure the selected files are copies (rather than links) and may have their contents revised and evolved independently of the project from which they were initially shared.
A new label is created by performing the label operation on the selected set of files in the project.
Caveats for using VSS:
• The get operation works properly for a workspace update only when you check out the files you want to change before making your local changes to them. If you modify your local copies, but don’t invoke the get operation until just before you are ready to check them in, then VSS wont know that your locally modified files were checked out before other versions that were checked in after you made your changes (but before you checked the files out). If you make sure to checkout the files before you make changes to your local copies, VSS will know to perform the merge operation for any files that you changed that also changed in the codeline
• VSS doesn’t effectively support a branching depth of more than 2 levels. If you do this, VSS wont remember the full merge ancestry more than one level deep and merging and reconciling changes back more than one level will be more difficult.
CVS - The Concurrent Version System
CVS is OpenSource software and is probably one of the most widely known and used
version control tools in common use today. CVS supports the majority of these pat-tern concepts using the copy-modify-merge model:
• Copy - A developer sets up a working directory and requests a working copy of the files in the project by checking out files from the project into the working directory. The syntax would be “checkout <options> <module-name>” (or “update <options> <codeline-name>” to populate the workspace with the latest files from the codeline).
• Modify - The developer edits any working copies of files in the working directory using the “checkout” command
• Merge - the developer performs a “commit” operation to checkin their mod-ifications to the repository
The main commands used are tag, checkout, update, and commit. One typically uses the
“-R” option with the update, commit, and tag commands to recursively apply to all files in the working directory. Branches for a codeline or a task branch are created using the “tag” command with the “-b” option. The “update” command synchronizes the developer’s workspace with the latest state of the named codeline. When the time comes to create a label (or, if desired, a checkpoint), the “tag” command can again be used (this time without the “-b” option).
TABLE 1-3. Mapping of SCM pattern concepts to CVS concepts
SCM Pattern concept name CVS concept name Comments
Repository Repository also known as CVSROOT
Development Workspace Working Directory or Working Copies
create using “cvs checkout -R ...” or “cvs update -R ...”; also see “cvs export”
Codeline branch create using “cvs tag -b”
Change Task N/A
Workspace Update update “cvs update”
Task-level Commit commit “cvs commit”
Task Branch branch create using “cvs tag -b”
Label tag see also rtag
Third Party Codeline vendor branch Use “cvs import -b”
As a special case, CVS was specifically designed to support the concept of a “vendor branch” (a THIRD PARTY CODELINE (10)). The “import” command was tailor made for this purpose!
Some caveats for using CVS:
• CVS doesn’t have as nice GUI support for branching and merging that many of the commercial tools have (but other OpenSource GUI’s exist and more seem to be written every year). This places the burden upon you to mentally draw the visual picture of the codeline and branching structure in your mind.
• CVS also isn’t quite as expert at tracking merge-history as some of the more advanced commercial tools. If a version has been merged, and a particular set of changes within the file were intentionally left unchanged (or changed differently), then subsequent merges will continue to present those same changes, even though the version they came from already had its differ-ences “reconciled.” Merge technology in many of the more capable version control tools know not to look at the contents of changes for versions that are already part of the “merge ancestry” of the current version.
Perforce
Perforce is a very commonly used, simple but powerful commercial VC tool with outstanding support for branching and merging. It bills itself the “fast software con-figuration management system” and prides itself on performance, and distributed TCP/IP client/server operation.
A repository in Perforce is called a depot. The Perforce server centrally manages access to the depot from connecting clients.
Perforce workspaces are called a client workspace and are configured by specifying a client spec to create a client view in the workspace. A codeline is called a branch in Per-force (as is a task branch). PerPer-force tracks the changes between parent and child branches, so it knows when a file version has already been merged and reconciled or not.
Perforce uses an “atomic change transaction” model where an operation either suc-ceeds on all files involved in an operation or else on none of them (an unexpected interrupt should never create a partially completed update or commit). Perforce’s branches (and resulting branch tree) are depot-wide rather than file-specific. This makes for a conceptually powerful branching model for managing parallel develop-ment with multiple codelines. (Other VC tools achieve this result with “projects” or
“workspaces” or “streams” using a hierarchical structure.) Perforce also has a means of allowing configurable change review notifications, daemons, and triggers to add customized checks and verification where desired.
TABLE 1-4. Mapping of SCM patterns concepts to Perforce concepts
SCM Pattern concept name Perforce concept name Comments
Repository depot
Development Workspace client workspace and client spec
p4 client and p4 sync
Codeline branch p4 branch and p4 integrate
Change Task changelist also see jobs
Workspace Update sync p4 sync and p4 resolve
Task-level Commit submit p4 submit
Task Branch branch p4 branch and p4 integrate -b
Label label p4 label and p4 labelsync
A Perforce workspace is setup by appropriately setting the P4PORT and P4CLIENT environment variables, and running “p4 client” to edit the client spec to the desired client view.
Once the workspace is setup and configured, “p4 sync” will populate the workspace with read-only copies of the latest files selected by the client spec. Changes are made by using the “p4 edit” command to obtain a writable copy of a file to modify.
The “p4 sync” command is also used to do a workspace update. Checked-out files will not be modified by “p4 sync.” A “p4 resolve” command must be used to reconcile the differences between the checked-out files and the latest versions in the codeline.
Files revised with the edit, add, and delete commands are added to a changelist that Perforce maintains for your workspace. Those changes can be committed to the depot using the “p4 submit” command. If any of your files aren’t the most recent version on the codeline, you will get a submit error. Submit errors and merge conflicts are resolved using the “p4 resolve” command. You can use “p4 resolve -n” to see which files need to be resolved.
Branches are created using “p4 integrate.” The integrate command can also be used with a branch spec to make the branch name automatically remember the mappings for the branched files. (This is convenient to use for codelines and task-branches when you have planned for them in advance.)
The “p4 label” command will create labels for releases, builds, and checkpoints. The
“p4 labelsync” command can revise the set of files belonging to a label.