Branching (see also)

Imagine that you've just released your product, and are beginning work on the next release. For the new release, you make a number of changes to several files and store those changes away as new trunk revisions using QVCS. A customer calls to report a problem with the recent product release. How can you repair the released code without getting the changes need to fix the bug confused with the work in progress for the upcoming release?

Use branching. With branching, you can go back to an earlier revision (the one associated with the earlier release), and use that as a new starting point for a different set of changes that you wish to make to a file. This new line of development is called a branch. It uses the branch point as the starting point for changes to the file, and is completely independent of any trunk revisions you may have added after the branch point. Branching effectively results in two (or more) separate paths of development for a single file.

The "trunk" path of an archive always describes the development path beginning with the initial revision 1.0 and continuing with revisions described by a single major.minor revision number pair. Branched revisions are identified by an additional major.minor revision pair appended to the branch's parent revision; i.e., the name of the parent revision is used as a prefix to all revisions along its branch path. For example, the first branch revision off of revision 1.0 would be called 1.0.1.1. The second revision on that branch would be 1.0.1.2, the third, 1.0.1.3, etc. If you were to create a second branch off of the same parent revision, that branch would begin with revision 1.0.2.1, followed by 1.0.2.2, 1.0.2.3, etc.

There is no limit to the number of branches that can start from a single parent revision. In addition, QVCS supports the branching of branches, up to a depth of 20.

Working with Branches

When lock-checking is enabled, QVCS will perform "automatic" branching. To automatically create a new branch, just lock the revision that you wish to serve as the branch point for a new branch. If that revision is not the newest revision on its branch, when you check in a revision to the QVCS archive, that new revision will start a new branch, and the revision that you had locked will become a branch point.

If you wish to create a branch off of the newest or tip revision in an archive, you will have to check the "Force a branch" option found in the check-in dialog or the -forcebranch switch on the qput utility. This will result in the revision being checked in as the first branch revision, with the trunk's tip revision as its parent.

QVCS also supports the concept of a "default branch." When QVCS first creates an archive file, the trunk is the default branch for that archive. This means that all QVCS utilities perform their work on the newest trunk revision by default. QVCS allows you to change the default branch to any other branch present in the QVCS archive (possible with File→Modify Archive→Default Branch dialog or the qmodhdr utility). This makes it easy to work on a series of changes on a branch path of development without always having to explicitly identify the branch revision as the one that you're interested in.

QVCS stores trunk revisions in reverse delta format. This means that the newest trunk revision is stored "as is" within the QVCS archive, while only the differences between older revisions are stored, so the newest trunk revision is always the fastest to retrieve. Branch revisions, on the other hand, are stored in forward delta format. This means that the branch revision that is closest to the trunk is faster to retrieve than those further away from the trunk, thus the oldest revision is the fastest to retrieve while the newest is the slowest.

See also: the Advanced Tutorial section on branching.