TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Version Control


Version Control Command Overview

You use the version control commands to save previous versions of files and to coordinate the work of multiple developers.

You can generally apply commands to files, views, or directories in views. When a command is applied to a view or a directory within a view, the command is recursively applied to all appropriate files and subdirectories.

Version control commands are based on the following concepts:

The version control commands that follow provide methods to:

Version control may be applied to data files and binaries as well as source code. Note that keyword replacement applies unless suppressed by using the -no_keyword_replacement option at check-in.


Version Control Context Switches

The following switches control version control characteristics of the associated view.

Inclusion and Exclusion Switches

Use the version control inclusion and exclusion switches listed above to determine which files can be controlled and accepted (by accept_changes) in views. The switches contain lists of names that can be fully-qualified or relative names that are resolved relative to the enclosing view.

The directory-oriented switches can use the naming expression "." to refer to the view itself.

A directory can contain controlled files if the following conditions are satisfied:

A file that does not have execute permissions set can be controlled if the following conditions are satisfied:

A file that has an execute permissions set can be controlled if the following conditions are satisfied:


Version Control Customization

The version control system may be customized through the use of version control triggers and extended version attributes.

Version Control Triggers

Triggers are operations that are invoked as a side-effect of normal version control operations. There are two types of triggers, namely pre-operation triggers and post-operation triggers.

Pre-operation triggers may be used to control whether or not the original version control operation will be executed. For example, the pre_check_out trigger can be used to determine whether or not the check_out command should be executed on a particular file.

Post-operation triggers may be used to associate additional functionality with version control operations. For example, the post_check_out trigger is executed whenever the check_out operation is successfully performed on a file.

Extended Version Attributes

Associated with each version in the version control database are a set of predefined attributes which record who, when and where the version was checked out and checked in. In addition each version has associated with it a set of notes which were entered by users.

In addition to the predefined attributes a version may also have a set of extended attributes which are defined at a particular site to meet the requirements of those users.

Defining Extended Attributes

The definition of extended attributes occurs in an attribute definition directory. The version control database of a subsystem may be associated with a particular attribute definition directory by setting either the VERSION_CONTROL_KEY switch in the subsystem's switch file or by setting the APEX_VERSION_ATTRIBUTE_KEY session switch to the name of the attribute definition directory.

Within the attribute definition directory are two files which define the characteristics of the extended attributes, namely the field definition file and the initial value file. These files define the attribute fields which will be supported and their initial values.

Defining Attribute Fields

The attribute fields which will be supported must be listed in the field definition file. The field definition file is named Fields and is found in the attribute definition directory. Each line in a field definition file has the format:

Blank lines and comment lines starting with "#" are also allowed in the field definition file.

Attribute field type information consists of a type name followed by an optional sequence designator. Furthermore enumeration fields are followed by the enumeration values.

The following attribute field type entries are recognized. Note that any field type may be followed by "*" which indicates that multiple values may be supplied for the field.

For example, a sample field definition file might contain the following entries:

Defining Attribute Initial Values

Initial values for extended version attribute may be specified in the initial value file, named Initial, in the attribute definition directory. The initial value file contains entries of the form:

For example, a sample Initial file might contain the following entries:

Using Extended Attributes

When the version control database of a subsystem contains extended attributes those attributes may be modified by the set_attribute and unset_attribute commands. Extended attributes may also be displayed using the show_status and show_versions commands.

The values of extended attributes are also available through keyword replacement through the same syntax as predefined attributes.


History Names

History names may be any legal simple name allowed by the UNIX file system. History names may not have an extension associated with another type of Apex object such as .wrk or .ss.

Special History Names

There are a number of a special history names which may be used as the value of command options to refer to other histories (primarily in the accept_changes command). You should not create actual histories with these names. The special history names include:


Version Numbers

Many commands take a specific version number as a parameter. You can specify version numbers in a variety of ways by integer values or strings.

Simple Version Numbers

A simple version number is either a string or a numeric value that specifies the number of a version within a particular version history. Simple version numbers are usually used in conjunction with a controlled file and specify a version in the history of the file.

A simple version number can be any of the following:

Full Version Numbers

A full version number, also known as a version name, is a string that completely specifies a version, independent of any controlled file.

A full version number string has the format:

<subsystem-name> <element-name> <history-name> <simple-version-number>

For example, the following is a full version name:


Keyword Replacement During Version Creation

Apex supports keyword replacement similar to that supported by RCS. During keyword replacement strings of the form $keyword$ and $keyword: $ are replaced with strings of the form $keyword: value$. The token keyword must be a known Apex keyword. For example, the keyword version can be used to cause a file to contain its version number.

Keyword replacement occurs as part of the check_in command and the contents of the checked in file are modified to reflect any changes caused by the replacement. Keyword replacement also occurs as part of any other command that creates a version. For example, when the control command creates a new version in a version history the new version is also subject to keyword replacement. Keyword replacement can be inhibited by using the -no_keyword_replacement option to any of the commands which create new versions.

Note that keyword replacement for new version creation or check in is implemented differently than other situations where it is used. During version creation "$element$" is not a keyword, it is an attribute. When a checked out file is to be checked in, Summit/CM looks for all strings enclosed by dollar signs ("$") in that file. For each such string, for example "$element$", Summit/CM constructs a keyword format "<object'element>". The replacement string of "<object>" is the full pathname of the file. The replacement string of "$element$" is exactly same as the output of the following apex report command.

The following should be noted concerning keyword replacement during version creation:

1 . There is no explicit keyword in the file being checked in. There is only one implicit keyword "<object>" whose replacement string is the full pathname of the file. In other words, you might want to do keyword replacement for new verion by providing attributes in dollar sign format, but you don't have choice to select the keyword and its context object.

2 . All attributes are valid as long as they are valid for keyword "<object>" with context object <filename>.

3 . There are special attributes definded only for new version creation. These are: version_log, header, id, locker, log, rcsfile, revision, source, and state.

There are additional attributes most likely used for the new version: subsystem, view, direcotry, object, version_name. In other situations, these attributes (subsystem, view, etc.) are usually treated as keywords, but here they are attributes. As a result, "$subsystem$" is equivalent to "<object'subsystem>" or "<subsystem>" in other place.

All the above are only applied to keyword replacement during check_in or new version creation process. In any other situations, for example, a new file is created from a prototype, makefiles of build management and the apex report command, Summit/CM dose normal keyword replacement.

To view a list of attributes and modifiers acceptable in a new version when it is checked in, use the following command in an Apex shell.

Valid keywords are also listed but some special keywords are not included. For example, the keywords "<name>", "<unit>", "<parent_unit>", "<unit_kind>" which are only valid in a new file prototype are not included in the output from this command.


Version Control Commands

Change Propagation

Change propagation, as embodied in the accept_changes command, is the process of updating one or more destination files to versions that have been supplied by one or more sources. For example, change propagation may be used to move the changes that have been made in a developer's personal working view into a system integration view for system testing. This section describes the various ways in which the arguments and options of the accept_changes command can be used to propagate changes.

Change Propagation Modes

There are two "modes" for change propagation, called integration mode and reconstruction mode. Integration mode causes the changes from the source to be integrated into the destination objects. This means that destination objects will usually only be updated to newer versions of the current history. History changes are not usually allowed in integration mode, however options are provided in order to specify the conditions under which history changes may occur.

Reconstruction mode results in the destination objects being made identical to the sources regardless of the current version or history of the destination. While integration mode is most useful in providing a controlled way of integrating changes from diverse sources, reconstruction mode is most useful in providing a way to set a destination object to have the identical contents of a single source. For example, reconstruction mode could be used to make the contents of one view identical to the contents of another view in the same subsystem.

The default mode is integration mode. Reconstruction mode is enabled by setting the -identical option.

Integration Mode

The updates that occur during integration mode are dependent on the current state of the destination objects and the type of source that has been specified. For example, destination files are usually only updated to later versions in the history which the file is currently associated with. Thus, no update would occur if the destination file already had a later version than the source file.

In the following sections, the default update semantics for various combinations of destinations and sources are described. In addition these updates are subject to a number of filtering and control options which are also described. For example, options can be used to restrict updates to only the destination objects which are currently associated with a specified history.

Updating to the Latest Version

Destination objects are updated to their latest version when the -latest option is specified. If the destination objects name files then those files are updated to the last checked in version of their current histories. If the destination objects name views or directories then all controlled files in the views or directories are updated to their latest version. Note that when the -latest option is specified no new objects are ever introduced into the destination.

Updating to Source Objects

Destination objects are updated to the versions associated with source objects when the -source option is specified. The -source option may specify either files or views.

When the -source option specifies files then the destination must specify views and the corresponding files in the destination are updated to the versions associated with the source files. If there is no file in the destination which corresponds to the source then a new file will be created unless the -existing option is set.

When the -source option specifies views then the destination may name either files, directories or views. When files are named the files are updated to the version of the corresponding source files. When directories or views are named then all existing files in the directories or views are updated to the versions associated with the corresponding source files. In addition new files are introduced into the destination directories and views as required.

Updating to Source Tasks

Only applies when Summit/TM is installed.

Destination objects are updated to the versions associated with specified tasks when the -source_task option is used. The details of this updated are described in the Summit/TM documentation.

Updating to Source Histories

Destination objects are updated to the latest versions of specified histories when the -source_history option is used. When the destination names files then only those files are updated. When the destination names directories or views the existing files are updated and new files are introduced if the history contains versions for elements for which there is no counterpart in the view or directory.

The special history names default_history, acceptable_history and current_history may be used as the value of this option to refer to the histories currently associated with a view. In particular, specifying -source_history current_history when updating a view will cause all version of existing objects to be updated to their latest version and any new objects associated with the acceptable histories, the default history or currently referenced histories will be introduced.

Updating to Source Versions

Specific versions to use in updating destination objects may be specified by using the -source_version option. The -source_version option may specify a single version or a file containing a list of version names.

Filtering Existing Objects Based on History

In integration mode the -history option may be used to limit the destination objects which will be updated. By default all destination objects may be updated, however if the -history option is set to name particular histories then only destination files that are currently associated with those histories will be updated.

Controlling the Introduction of New Files

In integration mode the introduction of new files into destination views may be controlled through the use the -existing and -new_history options. If the -existing option is set then no new objects will be introduced. If the -existing option is not set then the -new_history option is examined in order to determine objects will be created. Only new files with a history named by the -new_history option will be introduced into the destination view.

Propagation of Deletion

Deleted versions are propagated in the same way as any other version. Updating a file to a deleted version does have the effect that the file will be deleted when the update is complete.

Controlling History Changes

In integration mode, an existing file will only be updated to a version which is part of its current history. The -change_history option may be used to allow a file to be updated to a version in a different history (and in the process change its associated history). The value of the -change_history option is a list of history names. If a destination file is being updated from a source file with a different history and the destination file's history has lower precedence than the source file's history then the history and the version of the destination file will be changed to that of the source file. The precedence of histories is established by their order in the -change_history option as described in section History Precedence.

Reconstruction Mode

Reconstruction mode permits the contents of destination files, views and directories to be reconstructed from scratch independent of their current contents. A reconstruction mode update can be used to make the destination objects "identical" to the source.

In the following sections, the update semantics for various combinations of destinations and sources are described. Updates during reconstruction mode are not subject to any of the filtering options provided for integration mode.

Updating to the Latest Version

Updating to the latest version in reconstruction mode is identical to that in integration model with the exception that filtering based on the -history option is not provided.

Updating to Source Objects

Destination objects are updated to the versions associated with source objects when the -source option is specified. The -source option may specify either files or views.

When the -source option specifies files then the destination must specify views and the corresponding files in the destination are updated to the "exact" versions associated with the source files. This may result in the corresponding destination file being associated with an earlier version and/or a different history.

When the -source option specifies views then the destination may name either files, directories or views. When files are named the files are updated to the exact version of the corresponding files in the source view. When directories or views are specified then those directories and views are cleared of all existing controlled files and repopulated with files which correspond exactly to the controlled files in the source view.

Updating to Source Tasks

Only applies when Summit/TM is installed.

Destination objects are update to the exact versions associated with tasks when the -source_task option is used. If the destination names files then only those files are updated. If the destination names views or directories then any files in those directories which have corresponding versions associated with the task will be updated to those exact versions.

Updating to Source Histories

Destination objects are updated to the latest versions of specified histories when the -source_history option is used. When the destination names files then only those files are updated. The files will be updated to those versions even if this causes the history of the files to change to the specified histories.

When the destination names directories or views those directories or views are cleared of all existing controlled files and repopulated with controlled files which correspond to elements with versions in the specified source histories.

When a number of history names are supplied then they are subject to the normal history precedence rules described in History Precedence.

Updating to Source Versions

When the -source_version option is used, the destination files are updated to exactly the versions which are named.

History Precedence

Multiple histories and history precedence can be used to manage different variants of the same element. For example, multiple version histories might be used to represent platform variants. During change propagation it must be possible to decide which version history to use for new objects and whether or not the version history of existing objects should change. For example, if a non-platform specific object becomes platform specific then that history change might need to be propagated into interested views.

Sorting out which version history to use can be done by establishing a precedence between multiple histories. When multiple histories are used, the precedence between histories in a particular operation is determined by the order in which history names occur in the various history-valued options. History names which occur first in a list of histories take precedence over history names which occur later in the list. History precedence is applied to the value of the -new_history option in order to determine which history is selected for new controlled objects. History precedence is also applied to the value of the -change_history option to determine how the history of existing objects should be changed.

For example, consider a subsystem for which there will be Solaris and HPUX variants. The subsystems contains three histories called Common, Solaris, and HPUX which are used for common versions, Solaris-specific versions and HPUX-specific versions respectively. The subsystem contains two views named sol.wrk and hp.wrk in which the Solaris and HPUX variants are built. Changes would be accepted into the sol.wrk from a user development view tom.wrk with the command:

This command would ensure that Solaris histories always take precedence over Common histories and in particular if an object in tom.wrk was changed from the Common history to the Solaris history then that change would be propagated. However, a change from the Solaris history to the Common history (a less frequent occurrence) would not be propagated.

For another example, consider a task which contains both a Solaris and HPUX version. The command below would accept the Solaris version from the task but not the HPUX version:

In another example, the sol.wrk view could be populated with the latest versions of all objects in the Solaris and Common histories with Solaris versions taking precedence over Common versions.

Note that in this command the -change_history_deleted option will cause non-deleted Common versions to replace deleted Solaris versions. When the special value all is used to represent all current histories, then all histories are treated as if they have the same precedence unless the histories are specified in the -source_history option and then that order is used to establish precedence. For example, versions for new objects could be accepted with the following command:

In this case the source history values are processed one-by-one in the order given. In this way the Solaris versions will be accepted before the Common versions. Since the value of -change_history is all, all history changes are allowed and the actual precedence is established by the order of the histories in the -source_history option.

To summarize history precedence in change propagation:

1 . When multiple histories are involved in the introduction of new objects or in possible history changes, the relative precedence of the histories involved controls which history will be used.

2 . The precedence of the histories used for new objects is established by the order of histories in the -new_history option. If the value of the -new_history option is all and the -source_history option is set then the order of the histories in that option will establish precedence, otherwise there is no precedence.

3 . The precedence of the histories used for changing histories is established by the order of histories in the -change_history option. If the value of the -change_history option is all and the -source_history option is set then the order of the histories in that option will establish precedence otherwise there is no precedence.

Integration with Build Management

For views associated with Apex Ada and C++ compilers, compilation artifacts are propagated from source objects to destination objects in order to optimize compiler performance. Propagation of compiler artifacts can be disabled by using the -no_artifacts option.

RCS Migration

Specification of RCS histories to migrate, generally follows RCS naming rules:

1 . If a ",v" file is specified then the history in that file is migrated.

2 . If a source file is specified then the corresponding ",v" file is migrated. The ",v" file is found either in the directory containing the source file or in the "RCS" subdirectory.

3 . If a directory is specified then all ",v" files in that directory and in its "RCS" subdirectory (if present) are migrated.

4 . If a directory is specified which contains a file named "RCS" then that file is read to determine the location of a directory containing RCS history information which will be migrated.

For each RCS history to be migrated, an Apex version history is created in the history family named by the -migration_history option (also called the migration history). The Apex version history will contain the RCS revisions of the trunk. If the RCS history contains branches (besides the trunk) then additional Apex version histories are created in other history families. If an RCS branch contains has a symbolic name then the revisions in the branch will be placed in the Apex history family named "<migration-history-name>.<rcs-symbolic-branch-name>".

RCS migration requires RCS commands to be on the search list of the session.

SCCS Migration

Specification of SCCS histories to migrate, generally follows SCCS naming rules:

1 . If an "s." file is specified then the history in that file is migrated.

2 . If a source file is specified then the corresponding "s." file is migrated. The "s." file is found either in the directory containing the source file or in the "SCCS" subdirectory.

3 . If a directory is specified then all "s." files in that directory and in its "SCCS" subdirectory (if present) are migrated.

For each SCCS history to be migrated, an Apex version history is created in the history family named by the -migration_history option (also called the migration history). The Apex version history will contain all SCCS versions which were not part of a branch. Versions that are part of a branch are placed in a additional histories whose name is derived from the migration history and the branch number.

SCCS migration requires SCCS commands to be on the search list of the session.

Basic Status Output

In the non-verbose mode, the source control status for the view is displayed regardless of the version control state of the subsystem-wide Summit/CM database.

The format of the status information is shown below:

The first two lines provide the name of the view and the default history for the view.

The File Name field provides the name of each of the files selected by the filter options of the command. The file name will be preceded by "*" if the file is controlled and has a history that differs from the default history of the view.

The History field provides the name of the history associated with the controlled file or the word Uncontrolled if the file is not controlled.

The Version field specifies the current version for controlled files.

The State field provides the current version control state for controlled files. The possible values for this field are:

The Comments field is currently left empty for non-verbose status information.

Ada:

An example of status information is shown below:

C/C++:

An example of status information is shown below:

Verbose Status Output

Verbose status information has the same format as the basic status information; however, the information has additional annotations that show how the state of the files in this view compare to the overall state of the Summit/CM database.

When a controlled file does not have the latest version or is checked out in another view, its name is preceded by the character "-".

The Version field displays both the version of the current file and the latest version. For example, the value 2/3 is used to show that the current file has version 2 out of 3 possible versions.

The State field shows both the state of the current file and the state of the latest version. For example, the value In/Out is used to show that the current file is checked in, but a corresponding file with the same history is checked out in some other view. In verbose mode, the state field can have the following values.

The Comments field provides information about time, user, and view of check in/out, an indication when the file is not up-to-date, and an indication when a corresponding file is checked out in another view.

For example, when a file is checked out in another view, a line would be emitted of the form:

When a file is not up-to-date a line would be emitted of the form:


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS