![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Version Control
Version Control Command OverviewYou 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:
- A version is a snapshot of the state of a file at some point in time.
- A version history is a time-ordered sequence of versions that represents the history of a file. The versions in a version history are numbered from 1 to 65535
- A version history family is a set of version histories. A version history family includes at most one version history for each element in the subsystem. You can use version history families to group version histories that are related.
Each version history family has a name, is created by the create_history command, and is deleted by the delete_history command.
Multiple version history families are often used in multi-target development. For example, there might be version history families for Common, Sun4 and RS/6000 development. The Common history family would group the history for files that are target-independent, while the Sun4 and RS/6000 families would be used to group the history of all the files being developed for those targets.
Generally, this document uses the terms version history or history to refer to both version histories and version history families. The exact meaning should be clear from the context.
- A version control database contains all of the version history families associated with a subsystem. Each subsystem has a version control database.
- You can place each file in a view under version control. The file is associated with a version history, and the contents of the file reflect a particular version of that history.
There are some restrictions to this general rule:
- Version control is subject to the inclusion and exclusion switch settings for the view. See Inclusion and Exclusion Switches.
- A file cannot be placed under version control if it is nested in a directory with the name .Rational or with the extension .rtnl.
- When a file is under version control, you can modify the file only if it has been checked out. There are two types of check out, check out with reservation and private check out.
- A check out with reservation obtains an exclusive reservation on the version history of the file, thereby preventing any files with the same version history from also being checked out with a reservation. Checking out a file with a reservation starts a new version in the version history of the file. The version is completed, and the reservation on the history is relinquished when the file is checked in.
- A private check out
does not obtain an exclusive reservation of the version history of the file. A private check out allows modification of the file in the current view; however, it cannot be checked in unless it is upgraded to a check out with a reservation. A file can be privately checked out if its history is already reserved. A private check out is one way in which Apex supports simultaneous development by multiple users.Files in different views of the same subsystem are corresponding files if they have the same view-relative name. Corresponding files are associated with the same subsystem element and can share the same version history. When corresponding files have the same version history, you can check out with a reservation only one of the files at a time. When corresponding files have different version histories they can be checked out simultaneously. Each version has associated with it the user and time associated with its check out and check in, the view where it was checked out and checked in, and notes entered by the user. A deleted version is created when you delete a controlled file. A deleted version has the same properties as any other version. A controlled file is removed from the file system if its associated version is changed to a deleted version. Deleted version can be reconstituted by the recover command. Change propagation is used to move changes from one view to another. Changes may be propagated between corresponding files in views of the same subsystem. Propagating changes from a source file to a corresponding destination file results in the version associated with the destination file being changed to that of the source file. Customization of version control system may be accomplished through the use of triggers and extended attributes. Triggers allow the basic version control operations to be customized. Extended attributes allow custom information to be associated with each version. The version control commands that follow provide methods to:
- Place files under version control and remove them from version control (control, uncontrol).
- Check out and check in files to create new versions or abandon a check out in progress (check_in, check_out, abandon).
- Change the histories and versions of files under version control (set_history, set_version).
- Propagating changes between corresponding files in different views to support integration (accept_changes).
- Merge together changes from files that have been updated independently (merge).
- Migrate history from RCS or SCCS into Summit/CM. (migrate_history).
- Add notes to a version (note).
- Set extended attribute values (set_attribute, unset_attribute).
- Review information associated with views, files, and versions (show_status, show_histories, compare, difference, show_versions, show_version_image).
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 SwitchesThe following switches control version control characteristics of the associated view.
- VC_DEFAULT_HISTORY: history
Specifies the default history for a view. The default history is used whenever a new file is placed under source control.
Default value: "Common"- VC_ACCEPTABLE_HISTORIES: histories...
Specifies a set of histories for which controlled files can be accepted into the current view. The special value default_history allows this switch to refer to the value of the VC_DEFAULT_HISTORY switch. The special value all implies that all histories may be accepted.
The value of this switch is also used as the default value for the -new_history and -source_history options of accept_changes.
Default value: "default_history"
- VC_ACCEPTABLE_HISTORY_CHANGES: histories...
Specifies a set of history changes. Controlled objects in the current view are allowed to change their history to these values. The special value all implies that all histories may be accepted.The value of this switch is also used as the default value for the -change_history option of accept_changes.
Default value: " "- VC_ACCEPT_CHANGES_SOURCE: latest|objects|history
Specifies the default source type for the accept_changes command when run in the current view. The possible values are objects, history, and latest.
Default value: " "- VC_ACCEPT_CHANGES_SOURCE_OBJECTS: names...
Specifies the default source objects for the accept_changes command when the default source type is objects (as set in the VC_ACCEPT_CHANGES_SOURCE switch). This may name any objects but would generally be set to the name of a view from which the current view should be updated.
Default value: " "- VC_DIRECTORY_INCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of directories that can contain files under version control.
Default value: "*"- VC_DIRECTORY_EXCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of directories that are not to contain files that are under version control.
Default value: "Exports Imports Policy"- VC_FILE_INCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of files that can be placed under version control. This switch only applies to files that do not have any execute permissions set.
Default value: "*"- VC_FILE_EXCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of files that are not to be placed under version control. This switch applies only to files that do not have any execute permissions set.
Default value: "*~ Makefile"- VC_EXECUTABLE_INCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of files that can be placed under version control. This switch only applies to files that have some execute permissions set.
Default value: " "- VC_EXECUTABLE_EXCLUSIONS: names...
Specifies a string containing the names (possibly specified by wildcards) of files that are not to be placed under version control. This switch only applies to files that have some execute permissions set.
Default value: "*.csh *.sh"- VC_KEYWORD_REPLACEMENT_INCLUSIONS: names...
Species the names of files which can undergo keyword replacement during check in.
Default value: "*"- VC_KEYWORD_REPLACEMENT_EXCLUSIONS: names...
Specifies the names of files which should not undergo keyword replacement during check in.
Default value: "*.doc"- VC_VIEW_ATTRIBUTE: tokens...
Provided for user customization to allow users to specify an attribute of a view that can be tested by other switches. This switch has no built-in meaning.
Default value: " "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:
- Controlled files are allowed in any parent directories up to and including the view itself.
- The name of the directory is matched by any of the strings specified by the directory inclusion switch.
- The name of the directory is not matched by any of the strings specified by the directory exclusion switch.
A file that does not have execute permissions set can be controlled if the following conditions are satisfied:
- The file is nested in a directory that can contain controlled files.
- The name of the file is matched by any of the strings specified by the file inclusion switch.
- The name of the file is not matched by any of the strings specified by the file exclusion switch.
A file that has an execute permissions set can be controlled if the following conditions are satisfied:
- The file is nested in a directory that can contain controlled files.
- The name of the file is matched by any of the strings specified by the executable inclusion switch.
- The name of the file is not matched by any of the strings specified by the executable exclusion switch.
Version Control CustomizationThe 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:
attribute-field-name: attribute-field-type
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.
- date[*]
Designated an attribute field containing a date.
- enum[*] enum-values...
Designates an enumeration field. The values of the enumeration are specified as a set of tokens separated by blanks.
- fixed[*]
Designates a fixed point valued field.
- float[*]
Designates a floating point field.
- int[*]
Designates an integer valued field.
- path[*]
Designates a pathname valued field.
- string[*]
Designates a string valued field.
- task_path [*]
Designates a pathname valued field which names a task object.
- text
Designates a multi-line valued text field.
- version[*]
For example, a sample field definition file might contain the following entries:
# Define the current state State: enum in_progress implemented tested integrated # Information about who tested the version Tester: string Test_Date: date Test_Notes: text # Information about who integrated the version Integrator: string Integration_Date: date Integration_Notes: text # Dependencies on other versions Dependencies: version*
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:
- attribute-field-name: initial-value
This entry specifies that the designated attribute field will have the designated value when version 1 of an object is created.
The initial value may also contain keywords which will be evaluated at the time the initial value is set.
- attribute-field-name.inherit: true | false
Entries of this kind control whether initial values for successor versions are inherited from the previous version or initialized as if it were version 1. By default fields do not inherit values from the previous version.
For example, a sample Initial file might contain the following entries:
State: in_progress Tester: unknown Tester.inherit: true Integrator: unknown Integrator.inherit: true
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 NamesHistory 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:
- default_history
This name refers to the default history of the current view which is the value of the VC_DEFAULT_HISTORY context switch.
- acceptable_history
This name refers to the list of histories which are acceptable in the current view. The list of acceptable histories is specified as the value of the VC_ACCEPTABLE_HISTORIES context switch.
- current_history
This name refers to the list of histories which are currently used in the view. The list of current histories includes the current acceptable histories, the current default history, and any other histories associated with controlled objects in the view. For the purposes of history precedence, the list of histories is ordered with the acceptable histories occurring first, followed by the default history and with additional histories at the end of the list.
- all
This name refers to all of the histories which are currently defined in the subsystem. This value may only be used as the value of the -new_history, -history, and the -change_history filter options. Use of this value allows those filters to match all histories.
Version NumbersMany 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:
- Positive Integer (1 .. 65535)
Specifies an actual version number.
- Negative Integer (-65535 .. -1)
Specifies a previous version relative to the current version associated with some file.
- 65536
Specifies the last checked-in version.
- 65537
Specifies the last version (possibly checked out).
- 0 (zero)
Specifies the current version of a named file. For privately checked out files this will reference the privately checked out version.
- First
Specifies the first version (same as 1).
- Last_Checked_In
Specifies the last checked-in version (same as 65536).
- Last or Latest
Specifies the last version (same as 65537).
- Current
Specifies the current version for the object (same as 0).
- Previous
Specifies the version prior to the current version of the object (same as -1).
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:
/subs/base.ss unit.1.ada Common 2 (Ada) /subs/base.ss unit.C Common 2 (C/C++)
Keyword Replacement During Version CreationApex 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.
apex report -format "<object'element
>" <filename
>
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.
report -list_keywords
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 CommandsChange 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:
%apex accept_changes -source tom.wrk -new_history Solaris Common -change_history Solaris Common sol.wrk
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:
%apex accept_changes -source_task t1.task -new_history Solaris Common -change_history Solaris Common sol.wrkIn 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.
%apex accept_changes -source_history Solaris Common \ -new_history Solaris Common -change_history Solaris Common \ -change_history_deleted sol.wrk
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:
%apex accept_changes -source_history Solaris Common -new_history all \ -change_history all -change_history_deleted sol.wrkIn 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:
Current View: <view-name> Default History: <history-name> File Name History Version State ----------- -------------- ---------------- ------- <file-name> <history-name> <version-number> <state> . . . . . . . .
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:
- In
The controlled file is checked in.
- Out
The controlled file is checked out with a reservation.
- Private
The controlled file is checked out privately.
- Del
The controlled file is deleted and corresponds to a deleted version in the Summit CM database.
The Comments field is currently left empty for non-verbose status information.
An example of status information is shown below:
Current View: /test/lower.ss/tom.wrk Default History: Common File Name History Version State ------------ -------------- ------- ------ buffer.1.ada Common 1 In buffer.2.ada Common 3 Out list.1.ada Common 2 In list.2.ada Common 3 In queue.1.ada Common 2 Del queue.2.ada Common 2 Del stack.1.ada Common 1 In stack.2.ada Common 2 Private
An example of status information is shown below:
Current View: /test/lower.ss/tom.wrk Default History: Common File Name History Version State ------------ -------------- ------- -------- buffer.h Common 1 In buffer.C Common 3 Out list.h Common 2 In list.C Common 3 In queue.h Common 2 Del queue.C Common 2 Del stack.h Common 1 In stack.C Common 2 Private
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.
- In
The file is checked in and has the latest version.
- Out
The file is checked out with a reservation.
- Private
The file is checked out privately.
- Del
The file is deleted and there are no later undeleted versions.
- In/In
The file is checked in, does not have the latest version, and the history is not checked out in any other view.
- In/Out
The file is checked in, and a corresponding file with the same history is checked out in some other view.
- In/Del
The file is checked in, does not have the latest version, and the latest version is a deleted version.
- Private/In
The file is checked out privately, does not have the latest version, and the history is not checked out in any other view.
- Private/Out
The file is privately checked out, and a corresponding file with the same history is checked out in some other view.
- Private/Del
The file is privately checked out, and the latest version of the history is a deleted version.
- Del/In
The file is deleted, however, a new non-deleted version has been created for this history.
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:
- foo.1.ada Common 2/3 In/Out checked out in sam.wrk by sam on 01/07/94When a file is not up-to-date a line would be emitted of the form:
- foo.1.ada Common 2/3 In/In last checked in from sam.wrk by sam on 01/07/94
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |