Tutorial: Advanced Topics

This tutorial will cover the use of some of the QVCS command line utilities. This tutorial assumes you've already worked through the QWin tutorial, since it will make use of some of the QVCS archives you created in that tutorial, but any text file with an associated archive and two existing trunk revisions will do.

Contents

• Creating a Branch: Automatically and with -forcebranch
• Changing the Default Branch
• Using Floating Labels with Multiple Branches
• Merging Revisions
• Using qmerge to Eliminate Revision Changes
• Deleting Revisions

Creating a Branch

Branching is a tool that allows you to create separate paths of development for the same file. This can be useful if you need to return to a revision that was part of a previous release and make some changes--e.g., if you needed to fix a bug in the last release without adding any of the work-in-progress features for the next release.

To make use of branching, you must first create a QVCS archive that has more than a single revision. Let's take the opportunity to familiarize ourselves with the QVCS command line.

• Start a DOS command window. (From the Start menu, select Run... and enter "cmd" or "command" into the resulting prompt.)
• Make sure you have defined the QVCS_ID environment variable (QVCS command line utilities won't operate unless it is defined). For example:

  set QVCS_ID=ChrisSmith

  The value you use for your QVCS_ID environment variable here should be the same as one of the users that you defined for the access list in the previous tutorial.
• Change directories to the directory where you installed the QVCS executables. If you followed the installation defaults, use the command line:

  cd C:\Program Files\QVCSBin

• Check out readme.txt using the command line:

  qget -l readme.txt

• Using a text editor, make some changes to readme.txt. Save your edits.
• Check-in the readme.txt edits using the command line:

  qput readme.txt -comment "Some changes"

At this point you should have three revisions (1.0 and 1.1 from the QWin tutorial, and 1.2 that you just created) in readme.txt's QVCS archive. You can confirm this with the qlog command or QWin if you wish; if you confirm this with QWin, make sure to press the F5 key to refresh the display.

Now for branching. There are two ways to create a branch:

Automatic Branching

The simplest way is to check out a non-tip revision (any revision that is not the most recent on the trunk or on its branch), make your changes, and store the new revision in the archive. QVCS will automatically create a new branch, with the revision you locked originally as the branch point.

Let's make a branch off of the 1.1 revision. To do this, you must first get a lock on the 1.1 revision. Enter:

qget -l -r 1.1 readme.txt

Edit readme.txt, making some minor changes that are in a different area of the file than the edits you made to create revision 1.2. (We'll use these revisions later in the tutorial when you learn how to use qmerge.) Then, create the 1.1.1 branch with the command:

qput -comment "Your comment here." readme.txt

qput will report that you're creating the 1.1.1.1 revision. Notice that you didn't have to tell QVCS to create a new branch. This is the "automatic" branching feature. When you store a new revision within a QVCS archive that has lock-checking enabled, it looks for the revision that you've locked. If that locked revision is not a tip revision, it automatically turns the locked revision into a branch point and starts a new branch at that locked revision.

Use qlog or QWin to confirm that there are now four revisions within the QVCS archive. Notice the order that qlog displays them: 1.2, 1.1, 1.1.1.1, 1.0. qlog always displays revisions in the order that they appear within the archive. While trunk revisions are stored in reverse chronological order, branch revisions are stored chronologically following their branch point revision. Notice too, that the newest trunk revision is still revision 1.2. This means that a qget without specifying a revision number will still get the newest trunk revision (revision 1.2), even though revision 1.1.1.1 is newer than revision 1.2.

QWin supports this same kind of "automatic" branching. If you lock a non-tip revision in a QVCS archive that has lock-checking enabled, when you store your changes, QVCS will automatically store your new revision as the first revision on a new branch.

Creating Branches with -forcebranch

If you want to create a branch with the tip revision as your branch point, use the -forcebranch option. This flag is only necessary if the branch point is a tip revision. A tip revision is the newest revision on the trunk or on a branch.

• First, retrieve the newest trunk revision from the QVCS archive:

  qget -l readme.txt

• Edit readme.txt, again making some minor edits. Create the 1.2.1 branch using the command:

  qput -forcebranch -comment "Create the 1.2.1 branch" readme.txt

  qput will report that you're creating the 1.2.1.1 revision.
• Use qlog or QWin to confirm the existence of the new revision. Just like the 1.1.1.1 revision was stored after the 1.1 revision, the 1.2.1.1 revision is stored after the 1.2 revision.

QWin also supports creating a branch via the "forcebranch" method. To do so, enable the "force branch" check box on the Check-in File dialog box and you will create a branch just like in step 2 above.

« Previous - Next »