Tutorial: Advanced Topics

Merging Revisions

Merging has two typical uses: the first is to consolidate two separate sets of edits to the same file, and the second is to remove some intermediate revisions between two other revisions. The first use is more common.

Pretend for a moment that readme.txt was production code, and that you need to integrate the changes on the 1.1.1 branch with the latest changes on the trunk. How can you do this without manually re-entering all the changes from the 1.1.1 branch onto the latest trunk revision? Let's walk through the use of qmerge to solve this problem.

qmerge requires three input files: a common ancestor file, the first descendant file, and a second descendant file. It creates an output file that contains the merged edits of the two descendants, determining what the edits are by comparing them to the common ancestor.

In readme.txt, if we want to merge the edits of the 1.2 revision with the edits of the 1.1.1.3 revision, we need first to identify their nearest common ancestor. In this case, their common ancestor is revision 1.1. To use qmerge, we need to create these three files. Enter the commands:

qget -a expandkeywords=no -o r1_1.txt -r 1.1 readme.txt
qget -a expandkeywords=no -o r1_113.txt -r 1.1.1.3 readme.txt
qget -a expandkeywords=no -o r1_2.txt -r 1.2 readme.txt

Using the -o outputfile switch, qget retrieves each of the necessary revisions into the separate files specified, thus creating the three files that we need. Note that keyword expansion has been turned off. This prevents qmerge from having to worry about any differences between the files that occur simply because of differing keyword expansions. To create the output file containing the merged edits, enter the command:

qmerge r1_1.txt r1_2.txt r1_113.txt rmerge.txt

If any of the edits that you made to create these different revisions overlapped, qmerge reports the location of the overlap and flags it within the output file. Otherwise, qmerge creates an output file that contains both sets of edits, effectively consolidating the changes represented by the two separate lines of development.

Note that qmerge does not create a new revision with the merged file. If you wanted to store the consolidated edits as a new revision in the QVCS archive, you would first check out the default revision (assuming you wanted to add a new revision to the trunk), and enter the command:

qput -i rmerge.txt -comment "Merged 1.2 and 1.1.1.3 edits" readme.txt

where the -i infilename switch notifies QVCS that you want to store a revision using a different source from the typical work file (readme.txt). This will create revision 1.3.

QWin does not support the merge utility, but you could use it to store the merged file back into the QVCS archive, making sure to change the file listed in the "From the work file:" field of the Check-in Dialog.

Using qmerge to Eliminate Revision Changes

The second use of qmerge is to eliminate a revision or set of revisions between two other revisions. This circumstance could arise when trying to erase an ineffective change. For example, suppose the change you made in revision 1.1.1.2 introduced a bug, and that the way to repair the code is simply to remove the 1.1.1.2 changes. However, you want to preserve the 1.1.1.1 and 1.1.1.3 changes because they are associated with a completely different part of the code.

To do this, you again have to identify the three input files that qmerge will need to process. In this case, however, the "common ancestor" is the newest revision whose edits you want to delete, in this case the 1.1.1.2 revision. The two "descendant" files are the two revisions which frame the revision or set of revisions you wish to delete, in this case the 1.1.1.1 and 1.1.1.3 revisions. This works because qmerge recognizes the text of the 1.1.1.1 revision--where it differs from the 1.1.1.2 text which caused the bug--as an edit.

Let's use qmerge to eliminate the edits contained in the 1.1.1.2 revision, and yet preserve the edits made before and after. Enter the commands:

qget -a expandkeywords=no -o r1_111.txt -r 1.1.1.1 readme.txt
qget -a expandkeywords=no -o r1_112.txt -r 1.1.1.2 readme.txt
qmerge r1_112.txt r1_111.txt r1_113.txt rrevdel.txt

This merge effectively eliminates the edits made in the 1.1.1.2 revision. Note that this use of qmerge to eliminate revisions does not produce the same results as if you used the qdelrev utility. Had we used qdelrev to remove the 1.1.1.2 revision from readme.txt's QVCS archive, the edits described by the 1.1.1.2 revision would still be found in the 1.1.1.3 revision. That is, if you fetched the 1.1.1.3 revision from the QVCS archive, it would still have the changes that the 1.1.1.2 revision made. qdelrev deletes revisions from QVCS archives, but it doesn't remove the effects of those revisions (unless you're deleting a tip revision).

Again, note that qmerge does not store new revisions into a QVCS archive. To save the results of this merge, you must separately lock the archive, and then store the merged result back into the QVCS archive. In this case, you could do so with the following commands:

qget -l -label "MY_BRANCH" readme.txt
qput -i rrevdel.txt -comment "Eliminated 1.1.1.2 edits" readme.txt

This would create a 1.1.1.4 revision using rrevdel.txt as the file to store.

Deleting a Revision

On projects with many releases, the QVCS archives for the project can grow quite large, and will contain revisions of the file that date back to the beginning of the project. As a project matures, the older revisions are useless, and will never be needed again. With qdelrev you can get rid of those useless revisions and make the archive that much smaller. An added advantage of deleting useless revisions is that their information will no longer appear in your work files when the $Log$ keyword is expanded.

If, for example, we decided that after merging the 1.1.1.3 edits of readme.txt into the trunk, the 1.1.1 branch was unnecessary, we could delete the revisions on that branch using the command:

qdelrev -r 1.1.1.* readme.txt

Likewise, we could delete just a single revision, say revision 1.1.1.2, by using the command:

qdelrev -r 1.1.1.2 readme.txt

See the qdelrev utility reference section for detailed information on how to tailor which revisions qdelrev deletes, and for further command line examples.

Alternately, you can use QWin to delete revisions. To do so, you first select a file, and then use the File→Delete Revisions... menu command.

From both the command line and when using QWin, QVCS will ask you to confirm the deletion of the revisions that you have selected before actually deleting the revisions.

Before deleting revisions, it may be a good idea to make a backup of your archive files so that you could recover the deleted revisions if you had to.

« Previous - Next »