14. CVS Techniques

This section is obsolete for core XEmacs; we now use Mercurial 13. Mercurial Techniques. However these may be of some use for the packages, which are still in CVS for the moment.

14.1 Creating a Branch

This assumes that you have an existing workspace modified off of the main line, and you want to put it onto a branch.

1. Preliminary comment: All commands are to be executed at the top level of your workspace, unless otherwise indicated (which will be rare, if ever). Don't ever forget this and screw up, or you will get a real mess.

2. First, make a backup copy of your entire repository using cp -a (in the directory above your repository!) before doing anything.

3. Now, rule #1: Never try to create a branch from a workspace with added or deleted files. If you are lucky, the operation will simply fail. If you are less lucky, it will proceed, but make the adds and deletes on the main line, which you do not want at all. Therefore, you must undo all adds and deletes. To find out what is added and deleted, use something like cvs -n update >&! cvs.out, which does a "dry run". (You did make a backup copy first, right? What if you forgot the `-n', for example, and wasn't prepared for the sudden onslaught of merging action?) Take a look at the output file `cvs.out' and check very carefully for newly added files (marked with an `A') and newly removed files (marked with an `R'). Double check that your newly added files are in your backup copy, then rm and crw rm each of them to undo the addition. For each removed file, do crw add to undo the removal.

4. create a branch point. (This is a tag marking the point at which your branch split from the main line. It is extremely important to create such a branch point! The creation of the actual branch only creates a tag that marks the end of the branch, which will move as you check in changes to your branch. The CVS designers, in their infinite wisdom, didn't provide any automatic mechanism for tracking the branching point, so you need to do it manually.)

   crw tag ben-mule-21-5-bp

5. Next, create the actual branch:

   crw tag -b ben-mule-21-5

   Note that this doesn't actually do anything to your local workspace! It basically just creates another tag in the repository, identical to the branch point tag but internally marked as a "branch tag" rather than a regular tag.

6. Now, move your workspace onto the branch:

   cvs update -r ben-mule-21-5

   For unknown reasons, this may generate conflicts for each file that you have modified locally. If so, you can fix this by touching the conflicting files (the conflicts are bogus if you followed the above procedure). Run the following command in the top-level directory:

   cvs-mods | xargs touch --no-create

7. Now, carefully redo all adds and deletes; refer to the `cvs.out' file to remember what needs to be redone.

8. Now, check in the files on the branch:

   crw commit -m "first commit of ben-mule-21-5 branch"

14.2 Merging a Branch into the Trunk

Preliminary comment: Beware of the symlink problem with `cvs rtag':

cvs [rtag aborted]: received abort signal
cvs [rtag aborted]: received abort signal
lock.c:178: failed assertion `strncmp (repository, current_parsed_root->directory, strlen (current_parsed_root->directory)) == 0'
lock.c:178: failed assertion `strncmp (repository, current_parsed_root->directory, strlen (current_parsed_root->directory)) == 0'

It will fail with a message like this if the directory component of your root (CVSROOT environment variable or `-d' option) is a symbolic link, which is the case for the standard /pack/xemacscvs. You need to find the real directory name; one trick is to execute a command that attempts to write to the repository, using read-only access. This will output an error message showing the actual repository directory.

1. If you haven't already done a merge, you will be merging from the branch point; otherwise you'll be merging from the last merge point, which should be marked by a tag, e.g. `last-sync-ben-mule-21-5'. In the former case, create the last-sync tag, e.g.

   cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -r ben-mule-21-5-bp last-sync-ben-mule-21-5 xemacs

   (You did create a branch point tag when you created the branch, didn't you?)

   Note the way this command is specified, overriding the root to avoid the symlink problem, as described above.

2. Check everything in on your branch.

3. Tag your branch with a pre-sync tag, e.g.

   cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -r ben-mule-21-5 ben-mule-21-5-pre-feb-20-2002-sync xemacs

   Note, you need to use rtag and specify a version with `-r' (use `-r HEAD' if necessary) so that removed files are handled correctly in some obscure cases. See section 4.8 of the CVS manual.

4. Tag the trunk so you have a stable place to merge up to in case people are asynchronously committing to the trunk, e.g.

   cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -r HEAD main-branch-ben-mule-21-5-syncpoint-feb-20-2002 xemacs cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -F -r main-branch-ben-mule-21-5-syncpoint-feb-20-2002 next-sync-ben-mule-21-5 xemacs

   Use -F in the second case because the name might already exist, e.g. if you've already done a merge. We make two tags because one is a permanent mark indicating a syncpoint when merging, and the other is a symbolic tag to make other operations easier.

5. Make a backup of your source tree (not totally necessary but useful for reference and peace of mind): Move one level up from the top directory of your branch and do, e.g.

   cp -a mule mule-backup-2-23-02

6. Now, we're ready to merge! Make sure you're in the top directory of your branch and do, e.g.

   cvs update -j last-sync-ben-mule-21-5 -j next-sync-ben-mule-21-5

7. Fix all merge conflicts. Get the sucker to compile and run.

8. Tag your branch with a post-sync tag, e.g.

   cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -r ben-mule-21-5 ben-mule-21-5-post-feb-20-2002-sync xemacs

9. Update the last-sync tag, e.g.

   cvs -d :ext:xemacs@cvs.xemacs.org:/mnt/home1/cvsroots/xemacscvs rtag -F -r next-sync-ben-mule-21-5 last-sync-ben-mule-21-5 xemacs