CVS: Branching, Merging and Tagging

Introduction

CVS a.k.a. concurrent version system is the software version control in the field of software development.  Branching and Merging features in CVS allow developer to manage same piece of source file for several release and develop these release in parallel without interrupting each others.

Please note that the examples shown below are using WinCVS 1.2.

CVS Branching

For example, I have a file in CVS repository: App.DIY.Reg.pas.  The latest version for the file is 1.2 (The graph view is triggered with Ctrl+G Graph Selection):

Let look at the following scenario to see how could CVS branching manage the case:

I would like to make changes to a file.  These new changes is not yet ready for release to public. It may stay in CVS repository as internal or beta version for some time.  It will merge with main branch of the source file until it is mature.  However, the main branch may change due to bugs reported during the beta release period.  The bug fixed in main branch may merge with sub branch too during the beta release period.

The main trunk of a file in CVS is termed as “HEAD”.  You should define a meaningful name or tag to other branches but not the “HEAD” tag.  “HEAD” a reserve tag for main trunk.

Let us make some changes to local working versio of the file.  It will turn to red color once I make some changes:

The new changes is not ready for main release yet.  I am going to create a branch call BETA in version 1.2.  Please note that branch tag is case sensitive.

There are 2 ways to create a branch:

1. Access via main menu.  Modify | Create a branch on selection... :
   
   
2. Click the Fork Selection of Tags tool bar icon:
   
   

A windows with title “Create branch settings” prompt out:

Enter branch name and press OK button to create a “BETA” branch for the file.  We will leave an option “Check that the files are unmodified before branching” unchecked in this case.

The version of the file in graph view has a BETA branch shown:

Now everything seems ready and we are going to commit the local changes to BETA branch.  We will in trouble if we commit the changes now.  The changes we commit will stay in main trunk as version 1.3:

This is due to the sticky tag for the file in local copy is not mark as “BETA” tag.  It simply means we are working with the copy of main trunk in our local repository.  Whatever changes we commit will stay with main trunk:

We may update our local copy stick with "BETA” tag with CVS Update Selection:

Enter the stick tag “BETA” and press OK button to update your copy of file as BETA.

You will notice there is a tag BETA stick to the file after Update Selection.  Commit the local changes now and it will shown in BETA branch.  Please note also the file revision will update to 1.2.2.1 in this case:

We may remove the sticky tag and back to main trunk by checking an option “Reset any sticky date/tag/’-k' options” in Update Selection:

The local copy will become version 1.2 in this case:

We may always switch between HEAD and BETA branch by:

1. “Reset any sticky date/tag/’-k' options” in Update Selection
2. Retrieve rev./tag/branch of Stick options in Update Selection

respectively.

Now, assume we have another local working copy of the source with version 1.2 and empty sticky tag (a.k.a main trunk).  Perform Update Selection to this file will remain as 1.2.  It won’t update to 1.2.2.1 of BETA branch. unless we update the sticky tag to BETA.  We may continue making changes to version 1.2 and commit it as version 1.3, 1.4 or 1.5 and so:

CVS Merging

Let us back to version 1.2.2.1 of BETA branch.  We decided to merge the changes of 1.5 in main trunk to 1.2.2.1 of BETA branch.

Use the “Merge options” of Update Selection to merge main trunk into BETA branch:

Press OK button to proceed the merge operation.  Your local copy will then merge with main trunk.  You may decide to commit under BETA branch.  The following graph shows the result of commit work:

Now we decide to end the BETA branch and merge all changes from BETA branch to main trunk.  Let’s back to main trunk copy and perform the merging work:

After commit the changes, CVS repository will have the following version:

The version 1.6 is result of the merge of 1.5 in main trunk and 1.2.2.2 BETA branch.

CVS Tagging

CVS tagging allows you to mark an indication to a file for future reference.  A common usage for tagging is tag the source files with release or build number for future reference.  You may check out particular tag of source files for debugging purpose in future.

Here, we continue with CVS branching and merging example to use the CVS tagging feature to mark both 1.2.2.2 and 1.6 as “BETA_END”  and “BETA_MERGE” respectively.

To tag a version, use either:

1. Access via main menu.  Modify | Create a tag on selection... :
   
   
2. Click the Tag Selection of Tags tool bar icon:
   
   

A windows with title “Create tag settings” prompt out:

The following graph show the result of tagging:

The tagging is for reference only.  Remember that version 1.2.2.2 still exist in the CVS repository.  We may always go back to it anytime.

Working with main trunk and branch together in difference folders

When we start using branch in CVS repository, there may be a need to work with main trunk and difference branches together in same machine.  Check out a local copy from main trunk is easy:  Just check out as usual without any sticky tag.

Check out a local copy from branch may need extra care.  In real world example, only some of the source files may have branch.  Majority of source files may not have branch or already merge to main trunk.  If we check out a module with sticky options:

You will only get files with BETA tag:

This is not what we want in most situation.  We still need other files from main trunk in order to build a complete BETA release.  To check out the files from main trunk, check the option “If no matching revision is found, use the most recent one” :

Press the OK button and the local source copy will have:

The same usage is also applicable to Update Selection.

Now, you will see all files in your local copy have BETA sticky tag.  However, this doesn’t mean all files have BETA branch in CVS repository.  In the example, only App.DIY.Reg.pas has BETA branch and the rest are not.  This always confuse the CVS user.

Now, if you make changes to a file App.DIY.pas and you decide to put it in BETA branch.  If you attempt to commit the local changes in this example, you will encounter:

cvs commit: file `App.DIY.pas' had a conflict and has not been modified
cvs [commit aborted]: correct above errors first!

This is due to App.DIY.pas doesn’t has BETA branch in CVS repository, you have to create a new BETA branch for it first before you can commit.  Refer to CVS Branching in early section of this article.