Tutorial: Advanced Topics

Changing the Default Branch

When you created readme.txt's QVCS archive, the TRUNK was the default branch for the archive. In fact, it couldn't be any other way, since when QVCS creates an archive, the only branch that exists is the trunk. When a branch other than the trunk exists, QVCS lets you set that branch as the default branch in place of the trunk. This makes it easier to store and retrieve revisions on that branch, since you don't have to identify the revision each time you retrieve or lock a revision on the default branch. Let's set the default branch for readme.txt's archive to be the 1.1.1 branch so that we can work with that branch more easily.

• To change the default branch, enter the command:

  qmodhdr -defaultbranch 1.1.1 readme.txt

  Use qlog or QWin to confirm that the default branch is now the 1.0.1 branch instead of TRUNK. From QWin, to see which branch is the current default, select the "File Information" tab in the report pane. The "Default Branch:" will show 1.1.1 for readme.txt. (If you select another file, like tips.txt, it will show that its default revision is "TRUNK.")
• Now that the 1.1.1 branch is the default branch, you can work on the newest revision on that branch without having to explicitly identify the revision number. For example, enter:

  qget readme.txt

  qget reports that it fetched revision 1.1.1.1 without having to specify that revision number.
• Perform a locking qget this time:

  qget -l readme.txt

• Edit readme.txt again, making minor changes. Put the new revision back into the QVCS archive:

  qput -comment "More branch changes" readme.txt

  qput reports that you're creating the 1.1.1.2 revision. qput would have created this revision no matter which branch was the default since the revision that you locked was the 1.1.1.1 revision. (Had you used the -forcebranch option here, qput would have created the 1.1.1.1.1.1 revision.)
• You can change the default branch to any branch that exists within the QVCS archive with the qmodhdr utility. Let's change the default branch back to the TRUNK:

  qmodhdr -defaultbranch TRUNK readme.txt

QWin can also alter the default branch of an archive by using the File→Modify Archive→Default Branch menu command. The selection list displayed in the "Select Default Branch" dialog shows all the branches in the archive as well as the TRUNK. With QWin, whenever you select "the default revision" from a revision list, the operation will use the tip revision on the default branch associated with the archive. This is true for individual file operations as well as for project-level operations.

Using Floating Labels with Multiple Branches

Usually, a label is used to mark a specific revision within a QVCS archive. Floating labels allow a label to be always associated with the tip revision of the trunk or of a branch. This can be useful as work on a particular product release evolves into something more stable. Floating labels can also be a useful way to work on different branches of an archive without switching the default branch.

Let's create two different floating labels for readme.txt's QVCS archive. You create a floating label with qstamp or with QWin. With qstamp, the only difference between a floating label and a static label is that to create the floating label, you must enter a revision specification that identifies just the branch to associate the label with. This means that you omit the final minor revision number when defining the revision number associated with the label.

• Create a floating trunk label with the command:

  qstamp -r 1 -label "MY_TRUNK" readme.txt

  (note that the character following the -r is the number 1, not the letter L, indicating the path of trunk revisions comprised of 1.0, 1.1, and 1.2).
• Create a floating label for the 1.1.1 branch with the command:

  qstamp -r 1.1.1 -label "MY_BRANCH" readme.txt

• Floating labels are always associated with the tip revision of the branch that they describe. So when you use the command:

  qget -label "MY_TRUNK" readme.txt

  qget retrieves the tip trunk revision (1.2) from the QVCS archive.

You can also use QWin to apply a floating label by checking the "Make this a floating label" check box on the Label a file dialog.

Let's demonstrate the utility of floating label.

• Get and lock the tip branch revision using the command:

  qget -l -label "MY_BRANCH" readme.txt

  qget reports that it fetched the 1.1.1.2 revision, the tip revision of the 1.1.1 branch.
• Make some minor edits to readme.txt, and put the changes back into the QVCS archive using:

  qput -comment "My changes" readme.txt

  qput reports that it's creating revision 1.1.1.3. Since we changed the default branch back to the trunk, if you qget the default revision from readme.txt's QVCS archive at this point, you'd get the 1.2 revision (the newest TRUNK revision). However, with the floating label, you can get the latest revision on the 1.1.1 branch without having to know its revision number.
• Notice now that if you use the command:

  qget -label "MY_BRANCH" readme.txt

  qget reports that it fetched revision 1.1.1.3, the newest revision on the 1.1.1 branch. The MY_BRANCH label has "floated" to point to the newest revision on the branch that it's associated with.

Floating labels are also a useful way to create sets of files so you can use wildcard operations which only apply to the latest revisions of files that share the given label. For example, suppose there are three developers, John, Jane, and Ralph, who work on the same project containing 100 files. John usually works on 40 of the files, Jane usually works on 30 of the files, and Ralph usually works on the remaining 30 files. With floating labels, John could apply a floating label to just his files, Jane could apply a different floating label to just her files, and Ralph yet another different floating label to just his files. Each developer could then use wildcard gets to get just their files without having to explicitly name each file. A qget command line for John could look something like:

qget -l -label "John's files" *.*

This would get and lock only those files that had the "John's files" label. If that label were a floating label, it would get and lock the newest revisions of those files.

Since QWin supports get and check-out operations by label, once the floating labels were defined, you could use QWin to easily operate on these separate sets of files.

« Previous - Next »