7.3. Getting Hold of Collections and Package Versions

Turning to the version management command suite, let us recall how to create new collections and packages:

( -newcollection | -newcol | -newc ) <collection_name>
( -newpackage | -newpkg | -newp ) <package_name>

These commands have been introduced in Chapter 2. At this place, it suffices to add that every work package put in place by means of -newpackage is tagged devel_<package_name>_d0_0_0.

To check out existing package versions, you may use the command

[( -collection |-c) <collection_name>] (-checkout | -co) <tag> <package_name>+

If no collection name appears, then the corresponding collection must already have been created, and the command must be given within the ensuing collection directory. If a collection name does appear, then the working directory will be irrelevant, since the effect is that a collection directory will be created. Afterward, everything will proceed as if -checkout had been invoked, without -collection and the collection name, within that directory. Note that you may use the tag head to obtain the newest development version of each package whose name appears in the list.

Then, -update <tag> is to be used for version switching, the tag specifying where you want to switch to:

( -update | -up ) <tag>

This one is a standard command in so far as it must be given from within or below the root of a work package. You will mostly use it for switching to the development head or to the head of some release branch. The effect is that this version will replace the source files and the tagging of the current work package.

This replacement will not make the content of the current work package vanish. Rather, updates involve an automatic merge, where all pairs of version-controlled files are compared. In each case, the merge proceeds silently provided that there are no conflicts. ComPact will notify you provided that there are any conflicts. Also, the ensuing file will assume a special merge format. You will then have to edit the file manually to construct a new, valid version.

To merge some version into the current work package, you may use the explicit command

-merge <tag>

That version is designated by the tag. The effect is that merges of all pairs of version-controlled files are generated as described above, where the package tagging remains the same. For example, a typical necessity for using -merge occurs if bugfixes that have been applied to a release branch are to be incorporated into the main trunk. Simply type

pkgm -update head

followed by

pkgm -merge release_<package_name>_<major_number>_<minor_number>_stable

The ensuing merge versions will show all conflicts between the latest version on that branch and the latest development version. All what is left is to resolve them by appropriate editing.

Later on, you might want to incorporate further bugfixes that have been applied to the same release branch. The command -merge <tag1> <tag2> allows you to do that, since its effect consists of merging the differences between the versions designated by <tag1> and <tag2> into the current work package.

Finally, the following commands allow you to view version diffs:

If neither <tag1> nor <tag2> appear on the command line, then the current work package and the version designated by its tagging are considered; otherwise, the diff applies to the versions designated by <tag1> and <tag2>.