Copyright: Repository Mgmt Online Help - V9.0.2.90.7   Copyright © 1995, 2002, Oracle Corporation  All Rights Reserved


About the Version History Viewer

Related Topics

The Version History Viewer displays the version history of an object in the graphical form of a version tree.

Object versions are linked together by associations that record how each object version evolved from its predecessors. These associations make up the version tree, which shows succession, branching and merging of the object.

The Version History Viewer can display all versions of a single repository object (other than purged versions), regardless of the workarea in which the versions are visible.

You can run the Version History Viewer from any of the tools used for editing your objects.

From the Version History Viewer you can:

•	view the full version history of a single object  How

•	check in object versions from, and check out object versions to, your workarea  About

•	compare object versions  About

•	merge object versions  About

•	change the visible version of an object in the context workarea  How

When using the Version History Viewer, you can view further information about each version and customize the display using the many options supplied by the tool.  How

Version tree

The version tree is made up of a number of nodes, each representing a single object version. Nodes are connected to other nodes by lines (or edges). The top node is referred to as the root.

When you check in an object for the first time, an initial version is created, represented in the following diagram by version 1.0. The name or label assigned to the version depends on the version labeling policy.  About

All objects have a main line of development, the MAIN branch.

The version tree opposite shows a repository object after some development has taken place. A branch was created at version 1.1 called Release 1.1 bugfix. This branch also shows that further work was carried out and another version (1.1.1.0) was created.

Each new branch evolves in parallel to the MAIN branch. The branch that is on the right side of the version tree represents the most recently created branch. The leaf or tip node at the end of any branch represents the latest object version on the branch.

The line of nodes on the left hand side under the root node represents the main line (or branch) of development and is usually the default branch for an object. Using the Repository Object Navigator, you can create a new branch and set the new branch to be the default branch.  How

The red arrow in the diagram illustrates that changes made on the branch were merged back onto the main line of development at Version 1.4. The new object version created as a result of this merge represents the version that will be used in Release 2 of the product being produced. A merge is indicated by a line from a node on one branch to a node on the target branch.

Notes entered at checkin or checkout are displayed beneath the node. They can be toggled on and off from the toolbar.

Version labels are written across the nodes. An ellipsis is shown if a label is too long for the display.


About object checkin and checkout

Related Topics

When an object is created or imported into the repository it is added to version control when it is checked in for the first time. At this point a version of the object is created and a graphical representation of it may be viewed from the Version History Viewer.  About

Once an object is under version control the following rules apply:

•	a checked-in object version is read-only (write protected)

•	an object must be checked out before it can be modified

•	a checked-out object version can either be locked or unlocked  About

Checkin and checkout operations can be performed using the Version History Viewer or the tool in which you are editing your objects.

When you check in or check out objects, you can specify options and define notes for each object.  How

Notes are often used to describe the changes you have made to that version, for example to identify a bug fix. Any text you enter as a note is added as a comment to the selected object version. Details of the note can be viewed in full from the Version properties dialog box in the Version History Viewer, or on the object version itself in the Version History Viewer display area.

If the items selected for checkin or checkout are file system objects (files or folders mapped from a file system), checking in these objects automatically synchronizes the files with the repository before checking them in, and checking them out automatically synchronizes them with the mapped file system following checkout.  About

You can determine the display format used for object versions in the repository tools; you can choose between displaying object versions with their version labels, or with their branches, followed by their version numbers.  How

Checking in objects

When you check in an object, you add a new version to that object. The version that is visible in the current context workarea is checked in.

You can view a full version history of an object using the Version History Viewer. The object version currently visible in the current context workarea is marked with an arrow.

If you are checking in a version that is not checked out from the latest version on a branch, you must merge it with the latest version on the branch or check in to a new branch.

Checking in an object does not automatically check in the container that contains the object. If, therefore, you create an object in a container that is already checked out, and then check in the object for the first time, the object will not be viewable by other users until you explicitly check in the container as well.

When you check in an object that references other objects (for example, a module that references a table definition), make sure that you also check in all new and changed objects that are referenced, together with their container if it is not checked in. Doing so ensures that, if the same objects are visible in another workarea, the latest versions of those objects will be visible as soon as that workarea is refreshed.

If you have made changes to an object that is checked out on one branch, but want to apply these changes to another version of the same object on another branch, you cannot perform this operation directly. You must instead use one of the following methods, depending on whether or not you want to save the changes to the object version on the current branch, as well as to the object version on the other branch:

•	If you want to save the changes to the object version on the current branch, check in the object version on the current branch and then merge it with the object version on the other branch.

•	If you do not want to save the changes to the object version on the current branch, check in the object version on a new private branch, and then merge the changes with the object version on the other branch.

Checking out objects

When an object version is locked on checkout, other users can still check it out unlocked, but are prevented from either locking it or from checking it back in to the same branch until the lock is removed.  About

Using the Repository Object Navigator, you can also choose to apply or remove a lock on an object after it has been checked out.  How

If a strict locking policy is in force, every checkout is automatically set to locked. Because only one version of an object on a branch can be checked out locked, no further checkouts of that object on that branch can take place until the locked version is checked in.  About

When checking out an object version, you should ascertain whether it has a relationship to another object in the repository (for example, a table with a foreign key relationship to another table). You can do so by listing external references (for example, by choosing Utilities→External References in the Repository Object Navigator). If changes to both objects are required, you should check out both at the same time.

Checking out object versions not included in the current workarea

Working within the context of a workarea ensures that conflicts do not arise when several versions exist for a single object. The workarea is defined by a set of configurations or rules (or a combination of both) that select a single version of each repository object contained within a user’s schema. For example, a rule may state that all the latest object versions from a specific branch are included in the workarea.

If you want to check out an object version that is not included in the current workarea, you can redefine your workarea by modifying the workarea specification. Alternatively, you can use the Version History Viewer to select a different version of the object.  How

When an object version that is not the latest version is checked out, it must be merged with the latest version before checkin or checked in to a new branch.  About

Undoing checkouts

You can undo a checkout of an object version: this reverts the object to the state it was in prior to being checked out.

If you undo the checkout of a primary access element (PAC), any changes you have made to either the PAC or its component secondary access elements (SACs) are undone. For example, if you undo the checkout of a table, any changes to either the table, or the columns it owns, are undone. These changes include the deletion of any SACs; if you delete a column on a table and then undo the checkout of the table, the column will be restored.

If you undo the checkout of a folder, any changes you have made to the folder and the folder memberships are undone, but any changes to the elements contained with the folder are not undone. For example, if you make changes to a table in a folder and then undo the checkout of the folder, the changes to the table are not undone. If however, you create a new table and add it to a folder, and then undo the checkout of the folder, the table will no longer be accessible from the folder as its folder membership will be undone. The table itself will still exist, but will be positioned in the Lost and Found folder. Any elements contained within the folder that were deleted will be positioned in the Wastebasket; any such elements that were purged cannot be retrieved.

If you undo the checkout of an object version that has a relationship to another checked-out object in the repository (for example, a table with a foreign key relationship to another table), you should undo both checkouts at the same time. You can ascertain whether such a relationship exists by listing external references for the object version (for example, by choosing Utilities→External References in the Repository Object Navigator).


About locking on checkout

Related Topics

Two object states are available on checkout:

•	Unlocked

•	Locked

In addition, a strict locking policy can be applied.

The policy used for locking on checkout can be set by a user with the Set Policy system privilege.  How

If a strict locking policy is not in force, you can, providing the object is not already locked, change the lock status of any checked-out object.  How

Unlocked

When an object version is checked out in a workarea unlocked, other users in their workareas may also check out that version or any other version from the same branch. They can also check in their versions back to that branch. However, if multiple checkouts exist on an unlocked object, any subsequent checkins after the first checkin must be merged with the latest version on the branch.

Locked

When an object version is checked out in a workarea with a lock, other users can still check out a version of that object unlocked, but are prevented from either locking it or from checking it back in to the same branch until the lock is removed from the workarea. Only one version on a branch can be checked out locked; no further checkouts of that object on that branch can take place until the locked version is checked in again. If a strict locking policy is applied in the repository, every checkout is automatically set to locked.

The following diagrams illustrate what happens when unlocked and locked checkouts are performed on the same branch:

Unlocked checkout A user checks out unlocked object version 1.1 in Workarea A first.  Other users may also check out and edit the same version on which user in workarea A is working (or any other version on the branch). In this example, user in workarea B checks out the same version after user in workarea A. User in workarea A then checks her work back in before user in workarea B to create version 1.2.  To allow user in workarea B to check his work in he must now merge version 1.2 with his version to create version 1.3.
Locked checkout In this scenario user in workarea A checks out version 1.1 as locked first.  Other users can also check out this or any other version from the branch. However, they cannot check back in to the branch until the lock is removed from the workarea. In the illustration opposite, user in workarea B also checks out object version 1.1. After completing the changes, he must either check in to an alternative branch as the lock is still in force in workarea A (as shown opposite) or wait until user in workarea A checks in to create version 1.2 then merge with version 1.2 to create version 1.3 (as shown below).
In effect, checking out a version of an object with a lock reserves the tip of the branch for checkin. If you check out a version from the tip with a lock, other users cannot check in to the tip before you: therefore, you will not need to perform a merge operation.


About version labeling

Related Topics

A version label is a string that uniquely identifies each version of an object. Version labels are useful for identifying specific versions of objects with a meaningful textual description, instead of using a version number. Version labels can be viewed using the Version History Viewer or the Version Event Viewer.

Version labels may be created automatically by the repository or may be defined by the user, according to the repository policy set for version labeling. Repository policies can be set only by users with the Set Policy system privilege.  How

Version labels are applied to versions when those versions are checked in.

Automatic version labeling

If the repository version labeling policy is set to automatic, labels are generated automatically during each checkin operation as follows:

•	At initial checkin the version label 1.0 is assigned to the object version.

•	When a version is checked out, CO(1) is appended to the label. If another user checks out the same version, CO(2) is appended to the version label.

•	On each successive checkin to the same branch, the version number is incremented by 0.1. For example, version 1.4 becomes 1.5.

•	If you check in to a new branch, the value N.0 is appended to the first version on the new branch, where N = the number of the new branch from its origin. For example, if the current version is 1.1 (on MAIN), the first version on the second branch is 1.1.1.0 and the first version on the third branch, if it originates from MAIN is 1.1.2.0, and so on. However, if the third branch originates from, say, version 1.1.1.0 on the second branch, its first version is 1.1.1.0.1.0. This is illustrated below.

•	The version label assigned after a merge is the same as the label that would be assigned to the target version if it was simply checked in to the tip of its branch. For example, merging 1.3.1.7 (source) to 1.16 (target) results in version 1.17 if 1.16 was the previous tip node or 1.19 if the previous tip node was 1.18, and so on.

User-defined labeling

If the repository version labeling policy is set to user-defined, when checking in a version you can enter your own version label text in the Version label field in the Check In dialog box.

Each label name must be unique, otherwise conflicts can result. No two versions of the same object can share the same version label. However, the same version label can be used for different objects.

The maximum length of a version label is 32 characters.


About comparing repository objects

Related Topics

A compare operation compares two versions; a base object version and a contributor object version. The base object version is the version with which the contributor object version is compared. For example, if you choose to select version 1.1 of an object and compare it with its previous version 1.0, version 1.1 is the contributor and version 1.0 is the base.

The compare operation indicates:

•	additions to the contributor version that are not in the base version with which it is being compared

•	deletions from the contributor version that are not deleted in the base version with which it is being compared

•	changes to existing data in the contributor version that are not changed in the base version with which it is being compared

When comparing versions of objects, you can compare:

•	previous versions of the same object  How

•	other versions of the same object  How

•	versions of different objects of the same type  How

A compare operation can be performed on the following elements, both under version control and not under version control:

•	structured objects (standard repository objects including container objects)

•	Oracle Forms

•	files that are stored as text files

Because of the way in which structured data is stored in the repository, some issues need to be considered when comparing structured data.  About

The results of a compare operation are displayed in the Compare window. By default, the entire contents of both objects are displayed with the differences highlighted according to the nature of the difference, but you can choose to show only the differences and not the entire contents of the objects.  How

Note:	You cannot compare diagrams or binary files other than Oracle Forms.

Comparing with a previous version

If you select a version that is checked out to compare with its previous version, you are actually comparing the checked-out version details, including any changes made since checkout with the same version before it was checked out. This is illustrated in the following diagram.

	If you select the checked-out node, 1.1, and choose to compare with the previous version, this compares 1.1CO (1.1 checked out) with 1.1. However, if version 1.1 is checked in and you select it to compare with the previous version, this compares version 1.1 with version 1.0.

If the version you select to compare with the previous version is checked in but has no predecessor on the same branch, for example if it is itself the result of a branch, then its parent on the previous branch is selected for comparison.

Comparing Oracle Forms and associated files

When comparing Oracle Forms (files with the .fmb, .olb or .mmb extension), you need to provide some additional information for those Forms that use subclassing or referenced objects for sharing common objects and properties across your modules.

If the Forms you are comparing do use subclassing or referenced objects in other modules, the compare operation will perform correctly only if you provide additional information about:

•	the scope: the workarea or configuration in which the contributor and base Form versions participate

•	the path: the Forms path for the Form you want to compare

Note that when comparing Oracle Forms that use subclassing or referenced objects, you must ensure that:

•	each of the Form versions you are comparing is in a different workarea or configuration

•	the Forms path exists in every workarea or configuration used for the comparing operation

•	the files on the paths are uploaded into the repository  How

Forms that do not use subclassing or referenced objects can be compared in a similar way to other repository objects.


About the Version Event Viewer

Related Topics

The Version Event Viewer enables you to view details of all the events that have occurred for an object that is under version control.

Events occur whenever an object is checked in, checked out, locked, branched, or merged (purge events are not displayed). Checkout details are overwritten each time the object is checked in, so checkout details are only shown if the object currently has a checked-out version. Information is recorded against each event including:

•	the type of event

•	the version label

•	the name of the object

•	the branch on which the version resides

•	the date the event occurred

•	the user who initiated the event

•	notes about the event

You can run the Version Event Viewer from any of the tools used for editing your objects.  How

When using the Version Event Viewer, you can customize the details displayed to view events only between specified dates, and to rearrange the way in which report details are displayed.  How


About version control tools

Related Topics

The version control tools and utilities enable you to perform a number of tasks on both repository objects and file system objects. These include:

•	checking in and checking out objects to create new object versions  About

•	viewing the history of an object  About

•	viewing the events that occurred to an object  About

•	creating new version branches  About

•	comparing object versions  About

•	merging object versions  About

•	mapping file systems to the repository  About


About branching

Related Topics

Branches are sequences of object versions that have their starting point at a particular version in an existing branch, but evolve independently. All the versions together create a version tree. A version tree always has a MAIN branch, and may also have sub-branches. Branching enables you to develop multiple versions of a product simultaneously (parallel development) using the same set of source files.

When you check in an object for the first time, it is always added to the default MAIN branch. If the repository policy specifies an alternative branch to check in to for the first time, two versions are created, one on MAIN and the other on the specified alternative branch.

Branches can be created for specific tasks such as:

•	fixing bugs in a current release

•	making a start on the next release while simultaneously maintaining a component as part of a current release

•	maintaining different variants of the component (for example, to reflect different implementations, ports to different platforms, or interfacing with different window systems)

•	carrying out experimental development, which may eventually be abandoned or merged into the primary development

•	allowing two developers to concurrently make changes to a component and, therefore, enable serial updates to a component

Any work carried out on a branch can be merged back into the main development branch or into another branch at the appropriate time. About

The version tree for an object (see below for example) can be viewed using the Version History Viewer. About

By default, the versioning system uses an automatic branching policy. When the automatic branching policy is enabled, if a default checkin branch is set for a workarea, all checked-out objects for the workarea will check in to that branch. This feature is useful for isolating changes, for example, you may want to set up a workarea to isolate all the changes for a specific task, so ensuring that specific development branches are not populated with new object versions at critical periods in development, for example, during a build.

The implications of enabling or disabling automatic branching depend on a variety of factors as follows:

	Automatic branching enabled	Automatic branching disabled
No default checkin branch set for the workarea	The version is checked in at the tip of the current branch (the branch from which it was checked out).	The version is checked in at the tip of the current branch (the branch from which it was checked out).
The default checkin branch is the same as the current branch	The version is checked in at the tip of the current branch (the branch from which it was checked out).	The version is checked in at the tip of the current branch (the branch from which it was checked out).
The default checkin branch is different from the current branch	If the version does not already exist on the default branch, the version is checked in as the root of the new branch.  If the object already exists on the default checkin branch, the object will need to be merged. This involves checking in the latest version to the current branch, checking out the existing object from the default branch and merging from the checked-in latest version to the checked-out existing object on the default branch. The latest version can then be checked in on the default branch.	The version is checked in at the tip of the current branch (the branch from which it was checked out).
This is the first checkin for the object	The version is checked in to the MAIN branch, and a copy created on the default checkin branch.	The version is checked in to the MAIN branch.
When the automatic branching policy is enabled, you can change the default checkin branch for a workarea; when the automatic branching policy is disabled, you cannot change the default checkin branch.

The automatic branching policy can be set only by a user with the Set Policy system privilege.  How


About merging repository objects

Related Topics

A merge operation combines changes that have occurred independently in two versions of the same object. A merge is typically required when development has taken place on a branch and the changes need to be incorporated back onto the main line of development.

The merge operation takes two contributor object versions (target and source), compares them to a common ancestor version, and uses internal rules to create a result based on changes found in all three versions. The result is the target version updated; this becomes available as a new version only when it is checked in.

When merging object versions, you can choose to merge:

•	versions of a single object  How

•	versions of multiple objects  How

A merge operation can be performed on the following when under version control:

•	structured objects (standard repository objects including container objects)

•	files, both text and binary (including Oracle Forms)

Before you perform a merge, you should refresh your workarea and check in any containers that are new or checked out. Doing so ensures that new objects in these containers are brought into the workarea.

Because of the way in which structured data is stored in the repository, some issues need to be considered when merging structured data.  About

The differences and conflicts encountered by the merge operation are displayed in the Merge window. The Merge window also shows the selections proposed by the algorithm, and enables you to override those selections before the result is produced.

Note that when merging binary files other than Oracle Forms, the merge operation does not compare the source and target versions but instead copies the contents of the source over the contents of the target. No differences in the target will be retained.

Merge versions

As shown in the diagram below, a merge operation involves objects that each play one of the following roles:

•	Contributors: the source and the target. The source version must be checked in and the target version must be checked out.

•	The result, which contains those changes that have been selected. The result is the target version updated (and still checked out). This target version is placed on the target object's branch, and becomes available as a new version only when it is checked in.

•	A common ancestor. The merge algorithm automatically selects the closest common ancestor of the source and target. The ancestor is the latest version common to the branches containing the source and target versions.

The merge algorithm

A merge operation uses the merge algorithm; a set of rules for comparing two object versions with respect to a common object version and determining which differences should be implemented in a new composite object version. The algorithm requires that ancestor, source and target are versions of the same object, each on any branch, and the result is a new version placed on the target object’s branch.

The merge algorithm works with units of comparison found in the versions involved in the merge operation. The nature of a unit of comparison depends on the object type: for example, when handling text files, the merge algorithm selects clusters of new, changed, or deleted lines; when handling structured repository object types, a unit of comparison is a single property value. For some structured repository types, certain properties (for example, non-updateable properties such as the critical path properties on business functions) cannot be a unit of comparison, although they may appear in the Merge window.

A difference is a change in either the source or the target when compared to the common ancestor. A difference can be an addition, a subtraction, or a modification. Usually, the algorithm can make a correct selection (resolution) that will go forward into the new version.

Resolution of a difference occurs when two of the versions agree over a given unit of comparison. However, it is not the majority use of the unit that is selected by the algorithm, but the one that represents a change, as illustrated in the following table. If all three of the units are the same, no resolution is required. A conflict arises when the differences are such that they cannot be resolved by the algorithm.

Note that when merging binary files other than Oracle Forms, the merge operation does not compare the source and target versions but instead copies the contents of the source over the contents of the target. No differences in the target will be retained. To retain any of the information in the target, you need to perform a manual merge.

Example

An object version selected as the source version for a merge contains two text items: A, B. The version selected as the target is checked out, and contains text item C. The version selected by the algorithm as the common ancestor contains a text item C.

When a merge takes place, the checked-out target is updated to contain A, B, C.

If you now check in the target, the newly checked-in object version contains A, B, C, and the previous version of the target still contains C.

About merging and branching

A merge typically involves the latest version of an object on an offspring branch and a version of the object on the branch it originated from (ancestor branch), resulting in an updated version on the ancestor branch. After such a merge, the offspring branch can continue to evolve, for example to allow bug fixes to a release. Subsequent repeat merges can then take place with the ancestor branch to reflect further development. You can also merge to an offspring branch, so that changes can be propagated in both directions of the branch hierarchy.

Merges may be automatically started when you check in an object. When you try to check in a version of an object, a check is made to determine if the object is on the tip of its branch. If not, the checkin is refused, and you are prompted that a merge is required. For example, you may have checked out, unlocked, the latest version of an object. Another user may then check out the same version and check it back in again before you attempt to check in. In this case your version is no longer the tip version and a merge must be performed to enable this version to be checked in to the same branch.

Merging Oracle Forms and associated files

When merging Oracle Forms (files with the .fmb, .olb or .mmb extension), you need to provide some additional information for those Forms that use subclassing or referenced objects for sharing common objects and properties across your modules.

If the Forms you are merging do use subclassing or referenced objects in other modules, the merge operation will perform correctly only if you provide additional information about:

•	the scope: the workarea or configuration in which the ancestor, source and target Form versions participate

•	the path: the Forms path for the subclassed Form you want to merge

Note that when merging Oracle Forms that use subclassing or referenced objects, you must ensure that:

•	each of the Form versions you are merging is in a different workarea or configuration

•	the Forms path exists in every workarea or configuration used for the merging operation

•	the files on the paths are uploaded into the repository  How

Forms that do not use subclassing or referenced objects can be merged in a similar way to other repository objects.


Listing checkouts

Related Topics

You can display a list of all the repository objects in a selected context that are checked out, are not under version control or are new file system files. Other details are also displayed where applicable, for example, object type, checkout and checkin dates and other version details.

When you have displayed the list of objects you can then choose to:

•	check in all or selected objects

•	undo checkouts for selected objects

•	add new objects to version control (by checking in the objects)

•	compare an object version with its previous checked-in version

To list checkouts in a selected context:

1.	Choose Version→List Checkouts.

2.	In the List Check Outs: Criteria dialog box, specify the context and determine which of the objects within the context will be displayed in the List Checkouts dialog box.

3.	Click OK to display the List Checkouts dialog box.

4.	Choose the required action for each object:

•	To check in an object, select the object and click Check In.

•	To add an object to version control, select the object and click Check In.

•	To undo the checkout of an object, select the object and click Undo Checkout.

•	To compare an object version with its previous version, select the object and click Compare.


Editing the lock status of a checked-out object

Related Topics

When a checked-out object version is locked, other users can still check out a version of that object unlocked, but are prevented from either locking it or from checking it back in to the same branch until the lock is removed.  About

You can edit the lock status of a checked-out object only if a strict locking policy is not in force, and the object is checked out in the context workarea.

You can edit the lock status using the Repository Object Navigator.

To edit the lock status of a checked-out object:

1.	In the Repository Object Navigator, select the checked-out object for which you want to edit the lock status.

2.	Choose Version→Edit Lock Status.

3.	To lock the object, select the Locked option in the Edit Lock Status dialog box.

To unlock the object, deselect the Locked option in the Edit Lock Status dialog box.


Checking out object versions

Related Topics

When checking out objects you can choose to:

•	Check out specified object versions.  How

•	Check out all the object versions within a context (check out the 'contents' of the context element).  How

Depending on the type of context you can also choose to check out recursive subcontainers. Selecting this option checks out all subcontainers and their contents as well as the top level contents of the context. Examples of context elements are workareas and containers.

Only object versions that have already been added to version control (checked in) can be checked out. According to the policy used for locking on checkout, you may be able to lock the object versions when you check them out.  About

When checking out object versions you can also set other options as well as entering checkout notes.


Checking out specified object versions

Related Topics

Checkout operations can be performed using the Version History Viewer or the tool in which you are editing your objects.

As the Version History Viewer displays the evolution of a single repository object, you can use this tool to check out any version of a specified object.

The other tools enable you to check out more than one object at a time; the version of each object available for checkout is the version that is currently visible in the workarea (as defined by the workarea specifications).

To check out an object version using the Version History Viewer:

1.	Select the object you want to check out.

2.	Choose Version→View Version History.

3.	Select the node (object version) that you want to check out.

4.	Click

5.	In the Check Out dialog box, specify any checkout options and enter any notes that you want to associate with the object version.  How

To check out object versions using the other tools:

1.	Select the objects you want to check out.

Note:	Object versions that are checked in are displayed like this. Object versions that are checked out are marked by a tick ( · ).

2.	Choose Version→Check Out.

3.	In the Check Out dialog box, specify any checkout options and enter any notes that you want to associate with the object versions.  How


Checking out all object versions within a context

Related Topics

When checking out all the object versions within a context (checking out the 'contents' of a context), you can specify various options (depending on the type of context), including whether to recurse subcontainers, and whether to check out the context element itself. Examples of context elements are workareas and containers.

Selecting the Recurse subcontainer option checks out all subcontainers and their contents as well as the top level contents of the context element. Selecting the Check out sub-context itself option checks out the selected context element itself, as well as its contents.

To check out all the object versions within a context:

1.	Choose Version→Check Out Contents.

2.	In the Check Out Contents dialog box, select the context for the checkout and specify any checkout options.

3.	Click OK to display the Check Out dialog box.

If you selected the Preview checkout list option on the Check Out Contents dialog box, the Preview checkout dialog box is displayed, enabling you to specify which objects you want to check out.

4.	In the Check Out dialog box, specify any checkout options and enter any notes that you want to associate with the object versions.  How


Changing the visible version of an object in the context workarea

Related Topics

A workarea presents a version-resolved view of the repository; for each object that is selected in the workarea, only one version (usually the latest) of that object is ‘visible’. You may, however, want to work with another version of the object (the 'preferred version'), instead of the currently visible version. For example, you may have made some changes to an object in the latest version which are no longer needed, resulting in you wanting to revert to an older version of the object.

If the preferred version you select is not the latest version of an object, and you want to check in the preferred version, you must either merge it with the latest version on the branch or check it in to another branch so that it becomes the 'new' latest version on that branch.

To change the visible version of an object:

1.	Select the required object in the tool you are using.

2.	Choose Version→View Version History.

The version history tree of the object is displayed. The node that is currently visible in the context workarea is marked with an arrow.

3.	If the currently visible version is checked out, check in this version.  How

4.	Select the preferred version in the Version History Viewer.

5.	Check out the preferred version.  How

6.	Close the Version History Viewer, and return to the tool you are using.

7.	Choose Edit→Requery Selection in the tool you are using to display the preferred version instead of the original version selected in step 1.

8.	If the preferred version is not the latest version, and you want to check in the preferred version, you must make it the latest version by either:

•	merging it with the latest version on the branch  How

•	checking it into another branch  How


Viewing the version history of an object

Related Topics

You can view a graphical representation of the version history of an object using the Version History Viewer.  About

The Version History Viewer displays all versions of a single repository object that is under version control. The object version selected by the context workarea is marked with an arrow on the version tree.

The Version History Viewer can be run from any of the tools used for editing your objects.

Note:	The selected object must be under version control before you can view version history details.

To view the version history of an object:

1.	Select the object whose version history you want to view.

2. 	Choose Version→View Version History.

The version history tree for the selected object is displayed in the Version History Viewer.

3.	You may wish to view additional information about the version and customize the display.  How


Specifying checkin and checkout options and notes

Related Topics

To specify the same options and note for all objects:

1.	In the Check In or Check Out dialog box, ensure that all the objects are selected in the Objects selected for checkin/checkout box.

2.	Specify the options required.

3.	Enter the note required.

To specify different options and notes for each object:

1.	In the Check In or Check Out dialog box, select one object or group of objects in the Objects selected for checkin/checkout box.

2.	Specify the options required for the selected objects.

3.	Enter the note required for the selected objects.

4.	Select each object or group of objects in turn and continue with steps 2 and 3.


Entering user-defined version labels

Related Topics

A version label is a string that uniquely identifies each version of an object.  About

Version labels may be created automatically by the repository or may be defined by the user, according to the repository policy set for version labeling. Repository policies can be set only by users with the Set Policy system privilege.  How

Version labels are applied to versions when those versions are checked in. Within a single checkin operation, you can associate the same version label with all the selected object versions, or different version labels with different object versions.

To specify the same version label for all object versions:

1.	When checking in objects, in the Check In dialog box, ensure that all the objects are selected in the Objects selected for checkin box.

2.	Enter a label into the Version Label field. The label must be unique.

To specify different version labels for different object versions:

1.	When checking in objects, in the Check In dialog box, select one object version or group of object versions in the Objects selected for checkin box.

2.	Enter a label into the Version Label field. The label must be unique.

3.	Select each object version or group of object versions in turn and continue with step 2.


Checking in object versions

Related Topics

When checking in objects you can choose to:

•	Check in specified object versions.  How

•	Check in all the object versions within a context (check in the contents of the context element).  How

When checking in all the object versions within a context, you can also choose to check in recursive subcontainers. Checking in recursive subcontainers checks in all subcontainers and their contents as well as the top level contents of the context. Examples of context elements are workareas and containers.

Checking in an object does not automatically check in the container that contains the object. If, therefore, you create an object in a container that is already checked out, and then check in the object for the first time, the object will not be viewable by other users until you explicitly check in the container as well.

If you have made changes to an object that is checked out on one branch, but want to apply these changes to another version of the same object on another branch, you cannot perform this operation directly. You must instead use one of the following methods, depending on whether or not you want to save the changes to the object version on the current branch, as well as to the object version on the other branch:

•	If you want to save the changes to the object version on the current branch, check in the object version on the current branch and then merge it with the object version on the other branch.

•	If you do not want to save the changes to the object version on the current branch, check in the object version on a new private branch, and then merge the changes with the object version on the other branch.


Checking in specified object versions

Related Topics

You can check in specified object versions using the Version History Viewer or the tool in which you are editing your objects.

As the Version History Viewer displays the evolution of a single repository object, only one object can be checked in using this tool. The other tools enable you to check in several objects at once, including adding new objects to version control.

To check in an object version using the Version History Viewer:

1.	Select the object you want to check in.

2.	Choose Version→View Version History.

3.	Select the node (object version) you want to check in.

4.	Click

Tip:	You can also check in an object version by choosing Check In→<workarea/version name> from the right mouse button menu. This feature also enables you to view a list of all the versions of the object that are currently checked out in any workarea. You can check in only the version in your workarea.

5.	Specify any checkin options and notes you want to apply to the objects.  How

6.	Click OK.

A new object version is created and any comments you entered are associated with it.

7.	Click [image] to redisplay the version tree, showing the checked-in object version.

To check in objects using the other tools:

1.	Select the objects you want to check in.

2.	Choose Version→Check In.

3.	Specify any checkin options and notes you want to apply to the objects.  How


Checking in all object versions within a context

Related Topics

You can choose to check in all the object versions within a context using the List Checkouts dialog box. This dialog box displays all checked-out objects and objects that are not under version control in the current context.

When using the List Checkouts dialog box, you can also choose to view and check in recursive subcontainers. Checking in recursive subcontainers checks in all subcontainers and their contents as well as the top level contents of the context. Examples of context elements are workareas and containers.

To check in all the object versions within a context:

1.	Select Version→List Checkouts to open the List Checkouts: Criteria dialog box.

2.	In the For box, specify the workarea and sub-context that will form the basis for your list of checked-out objects.

3.	In the Show box, specify which kinds of objects you want to display.

4.	If required, select Recurse subcontainers to display subcontainers.

5.	In the Checked out/Created box, specify whether you want to display objects checked out or created by yourself or by anybody.

6.	Click OK to display the List Checkouts dialog box.

7.	Select the objects you want to check in.

Tip:	To check in all the objects, click the Select All button.

8.	Click Check In to display the Check In dialog box.

9.	In the Check In dialog box, specify any checkin options and enter any notes that you want to associate with the object versions.  How


Merging versions of a single object

Related Topics

When merging versions of objects, you may wish to:

•	merge versions of a single object (as described in this topic)

•	merge versions of multiple objects (particularly useful when, for example, merging entire contents of workareas)  How

You can merge versions of a single object using either the Version History Viewer or the Repository Object Navigator.

In any merge operation, you select a source version and a target version. The source version must be checked in and the target version checked out. The target version (checked out) will be updated to contain the result. When the target version is next checked in, a new version will be created.

Because of the way in which structured data is stored in the repository, some issues need to be considered when merging structured data.  About

Note that when merging binary files other than Oracle Forms, the merge operation does not compare the source and target versions but instead copies the contents of the source over the contents of the target. No differences in the target will be retained. To retain any of the information in the target, you need to perform a manual merge.

To merge versions of a single object in the Version History Viewer:

1.	Select the object for which a merge is required.

2.	Choose Version→View Version History.

3.	Select the target object version you want to include in the merge.

4.	If it is not already checked out, check out the target version.  How

5.	Mark the checked-out target version.  How

6.	Select the second object version (the source version) you want to include in the merge.

7.	Click Merge to mark from the right mouse button menu.

8.	In the Merge confirmation dialog box, choose whether to preview the merge results in the Merge window, or to perform an automatic merge if there are no conflicts.

9.	If you are merging an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

10.	If the Merge window is displayed, preview the selections made by the merge algorithm, make selections to override them if necessary, and resolve any conflicts.

For each difference block, the checkboxes indicate which form of the comparison unit the merge algorithm has selected to go forward to the result. If none of the boxes is selected, this indicates a conflict; you must resolve the conflict.

•	To accept the selection, leave the checkboxes unchanged.

•	To override the selection made by the algorithm, select the checkbox next to the form of the comparison unit you want to go forward into the result.

•	To resolve a conflict, select the checkbox next to the form of the comparison you want to go forward into the result. If the conflict is for a file or for multi-line text, you can select more than one form of the comparison to go forward to the result; if the conflict is for structured repository object types, you can select only one.

Tip:	When merging files, you can edit the text in the files directly from the Merge window.  How

11.	Click Save to update the (checked-out) target version so that it contains the result.

Note:	No new version is created until the updated target is checked in.

To merge versions of a single object in the Repository Object Navigator:

1.	In the Repository Object Navigator, select the target object version for which a merge is required.

2.	If it is not already checked out, check out the target version.  How

3.	Choose Version→Merge.

4.	In the Select source version for merge dialog box, choose the version that is to be the source of the merge.

5.	In the Merge confirmation dialog box, choose whether to preview the merge results in the Merge window, or perform an automatic merge if there are no conflicts.

6.	If you are merging an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

7.	If the Merge window is displayed, preview the selections made by the merge algorithm, make selections to override them if necessary, and resolve any conflicts.

For each difference block, the checkboxes indicate which form of the comparison unit the merge algorithm has selected to go forward to the result. If none of the boxes is selected, this indicates a conflict; you must resolve the conflict.

•	To accept the selection, leave the checkboxes unchanged.

•	To override the selection made by the algorithm, select the checkbox next to the form of the comparison unit you want to go forward into the result.

•	To resolve a conflict, select the checkbox next to the form of the comparison you want to go forward into the result. If the conflict is for a file or for multi-line text, you can select more than one form of the comparison to go forward to the result; if the conflict is for structured repository object types, you can select only one.

Tip:	When merging files, you can edit the text in the files directly from the Merge window.  How

8.	Click Save to update the (checked-out) target version so that it contains the result.

Note:	No new version is created until the updated target is checked in.


Merging versions of multiple objects

Related Topics

When merging versions of objects, you may wish to:

•	merge versions of a single object  How

•	merge versions of multiple objects (as described in this topic)

Merging versions of multiple objects at the same time is particularly useful when, for example, merging entire contents of workareas. A merge operation combines changes that have occurred independently in two versions of the same object.

You can merge versions of multiple objects using the Merge Wizard, accessible from the Repository Object Navigator.

Before a merge operation can be performed, the source versions must be checked in and the target versions checked out. The target versions (checked out) will be updated to contain the result. When the target versions are next checked in, a new version for each target will be created. If you have not already checked out the target versions, the Options page of the wizard provides you with an option for automatically checking out these versions.

Because of the way in which structured data is stored in the repository, some issues need to be considered when merging structured data.  About

Note that when merging binary files other than Oracle Forms, the merge operation does not compare the source and target versions but instead copies the contents of the source over the contents of the target. No differences in the target will be retained. To retain any of the information in the target, you need to perform a manual merge.

To merge versions of multiple objects:

1.	In the Repository Object Navigator, choose Tools→Merge Wizard.

2.	Follow the on-screen instructions for specifying the information required for the merge operation. Online help is available for each screen of the wizard.

3.	Click Finish to start the merge operation.

4.	If you selected the View list of objects before merging option, the Merge list window is displayed, enabling you to view the list of merge candidates, to instigate the comparing and merging of objects, and to explicitly check in and check out objects.

5.	If you are merging any Oracle Forms and the Forms use subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed for each Form, enabling you to define the scope and the path for the Form.

6.	The Merge Wizard processes each selected item in the list in turn; if appropriate, in each case the Merge window is displayed for you to preview the selections made by the merge algorithm, and to make selections to override them if necessary.

For each difference block, the checkboxes indicate which form of the comparison unit the merge algorithm has selected to go forward to the result. If none of the boxes is selected, this indicates a conflict; you must resolve the conflict.

•	To accept the selection, leave the checkboxes unchanged.

•	To override the selection made by the algorithm, select the checkbox next to the form of the comparison unit you want to go forward into the result.

•	To resolve a conflict, select the checkbox next to the form of the comparison you want to go forward into the result. If the conflict is for a file or for multi-line text, you can select more than one form of the comparison to go forward to the result; if the conflict is for structured repository object types, you can select only one.

Tip:	When merging files, you can edit the text in the files directly from the Merge window.  How

7.	In the Merge window, click Save to update the (checked-out) target version so that it contains the result.

Note:	If the Check in objects after merging option was set on the Options page of the wizard, each updated target version is checked in automatically. If the option was not set, no new versions are created until the updated targets are checked in.


Hints and tips for merging structured data

Related Topics

Because of the way in which structured data is stored in the repository, some issues need to be considered when merging structured data.

Issue	Solution
• When merging any two objects, you choose which specific properties of those objects should be included in the merge operation. Some combinations of properties are invalid.  For example, if you choose to merge a property of datatype CHAR 240 with a property of datatype NUMBER 38, the length of the number cannot be extended to 240.	Merge only those properties for which a combination is valid.
• When merging any Primary Access Elements (PACs) that have Secondary Access Elements (SACs), you cannot merge the actual SACs that have been added but must accept, reject or take both. If both PACs have a SAC with the same name, taking both SACs will cause the merge operation to fail.  For example, a user working on one version of a table may create a column entitled 'Name'. Another user working on another version of the same table may also create a column entitled 'Name'. The merge operation of these two versions of the table will fail.	Cancel the Merge and change the name of one of the SACs before repeating the merge operation Or Reject one of the SACs and complete the merge operation. Then manually copy the rejected SAC to the merged version, renaming it at the same time.
• Element types that reference other objects, and that have their uniqueness defined by the reference, cannot be merged with other element types that reference the same object.  For example, two table implementations within a database user may both reference a table entitled 'Emp'. These two table implementations cannot be merged because the table Emp will appear twice in the Merge Window.	Accept the latest version on the assumption that this contains the latest changes, and then check the object once it has been merged. Or Use the Compare Window to view the differences between the two objects. Then display each object in a different Navigator and Property Palette, and manually copy and paste the changes required.
• Merging objects that use sequences may alter the sequence.  For example, if you merge a version of an object that uses a sequence for its properties with another version of an object that contains new properties, the new properties may alter the sequence.	Accept the sequence for one object (the sequence closest to the desired result) and then check this sequence in the Navigator, and adjust it if necessary.
• When merging PACs that reference other SACs of the same PAC, all the SACs being referenced must be included in the merge operation.  For example, if you are merging a PAC that has a primary key dependent on a column (via a key component), the column must be included in the merge operation as well as the primary key.	Ensure that you include all referenced SACs within the merge operation.
• Merging objects that depend on different versions of the same SAC object may fail as the different versions of the SAC may not be visible in the workarea.  For example, if your workarea rules are set up to show the latest versions, merging an object that depends on a previous version of a SAC will fail as the version will not be visible in the workarea.	When merging objects that depend on other objects, always merge the objects that are being depended on first.


Comparing versions of different objects of the same type

Related Topics

When comparing versions of objects, you may wish to:

•	compare previous versions of the same object  How

•	compare other versions of the same object  How

•	compare versions of different objects of the same type (as described in this topic)

When comparing versions of different objects of the same type, the objects can reside in the same workarea or in different workareas. Only objects of the same type can be compared.

A compare operation involves a base object version and a contributor object version. The base object version is the 'different' object version with which the contributor object version is compared.

You can compare versions of different objects of the same type using the Repository Object Navigator.

Because of the way in which structured data is stored in the repository, some issues need to be considered when comparing structured data.  About

Note:	You cannot compare diagrams or binary files other than Oracle Forms.

To compare versions of different objects of the same type:

1.	In the Repository Object Navigator, select the contributor object, followed by the base object.

Tip:	Click and hold down the Shift key to select more than one object.

2.	Choose Utilities→Compare.

Note:	If you did not select a second object, the Select Second object for Compare dialog box is displayed.

3.	If you are comparing an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

4.	In the Compare window, use the Next and Previous buttons to navigate through the differences.  How


Comparing previous versions of the same object

Related Topics

When comparing versions of objects, you may wish to:

•	compare previous versions of the same object (as described in this topic)

•	compare other versions of the same object  How

•	compare versions of different objects of the same type  How

A compare operation involves a base object version and a contributor object version. When comparing a version against a previous version, the previous version is the base version with which the contributor object version is compared.

Because of the way in which structured data is stored in the repository, some issues need to be considered when comparing structured data.  About

You can compare a version of an object with a previous version using the Version History Viewer or the tool in which you are working.

Tip: 	If the contributor version is checked out, you can also compare an object version with its previous version using the Compare button on the List Checkouts dialog box.

Note:	You cannot compare diagrams or binary files other than Oracle Forms.

To compare an object version with its previous version using the Version History Viewer:

1.	Select the object you want to include in the compare operation.

2.	Choose Version→Version History Viewer.

3.	Select the contributor version that you want to compare with its previous base version.

4.	Choose Compare with previous from the right mouse button menu.

Note:	If the contributor object version is checked out, this option compares it with the same version in its checked-in state.  About

5.	If you are comparing an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

6.	In the Compare window, use the Next and Previous buttons to navigate through the differences.  How

To compare an object version with its previous version using the other tools:

1.	Select the object you want to compare with its previous version.

2.	Choose Version→Compare Previous Version.

Note:	If the current object version is checked out, this option compares it with the same version in its checked-in state.  About

3.	If you are comparing an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

4.	In the Compare window, use the Next and Previous buttons to navigate through the differences.  How


Comparing other versions of the same object

Related Topics

When comparing versions of objects, you may wish to:

•	compare previous versions of the same object  How

•	compare other versions of the same object (as described in this topic)

•	compare versions of different objects of the same type  How

A compare operation involves a base object version and a contributor object version. The base object version is the 'other' version of the object with which the contributor object version is compared.

You can compare a version of an object with any other version of the same object using the Version History Viewer or the Repository Object Navigator.

Because of the way in which structured data is stored in the repository, some issues need to be considered when comparing structured data.  About

Note:	You cannot compare diagrams or binary files other than Oracle Forms.

To compare an object version with any other version using the Version History Viewer:

1.	Select the object whose versions you want to compare.

2.	Choose Version→Version History Viewer.

3.	Mark the first node (the contributor version) to be included in the compare operation.  How

4.	Select the second node, the base version with which the marked contributor will be compared.

5.	Choose Compare with mark from the right mouse button menu.

6.	If you are comparing an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

7.	In the Compare window, use the Next and Previous buttons to navigate through the differences.  How

To compare an object version with any other version using the Repository Object Navigator:

1.	In the Repository Object Navigator, select the object you want to compare with another version.

2. 	Choose Version→Compare Other Version.

3. 	Select the other version (the base version) from the list and click OK.

4.	If you are comparing an Oracle Form and the Form uses subclassing or referenced objects, the Select Paths for Inherited Classes dialog box is displayed, enabling you to define the scope and the path for the Form.

5.	In the Compare window, use the Next and Previous buttons to navigate through the differences.  How


Hints and tips for comparing structured data

Related Topics

Because of the way in which structured data is stored in the repository, some issues need to be considered when comparing structured data.

Issue	Solution
• You may have two different versions of a Primary Access Element (PAC) and have created the same Secondary Access Element (SAC) for each PAC. As the SACs are created in different versions of the PAC, the compare operation will not recognize them as being the same, but will instead highlight them as a difference.  For example, a user working on one version of a table may create a column entitled 'Name'. Another user working on another version of the same table may also create a column entitled 'Name'. The compare operation will not recognize these two columns as being the same.	Pay special attention when comparing any PACs that have SACs with the same name.
• If the properties of a SAC differ between two versions, any differences are highlighted in the Compare window against the properties and not against the owning SAC. For example, a user working on one version of a column may change the maximum length of that column. The compare operation will highlight the difference in the Compare window against the Maximum Length property, and not against the owning column.	When comparing structured data, choose to display only the differences between the two object versions in the Compare window, instead of the entire contents. How


Marking a node in the Version History Viewer

Related Topics

You mark a node in the Version History Viewer when you want to perform an operation that involves the selection of two object versions. You then select a second object version and compare or merge it with the marked node.

To mark a node:

1.	In the Version History Viewer display area, select the node (object version) you want to mark.

The blue cornered highlight selector indicates that the node is selected.

2.	Choose Mark node from the right mouse button menu.

A red triangle appears in the top left hand corner of the highlight selector to indicate that this node is now marked.

3.	Select a second object version.

The blue cornered highlight selector indicates that the node is selected.

Marked and selected nodes are illustrated in the following diagram.

	The selected node is indicated by the blue cornered highlight selector. The node that is selected by this user’s workarea is marked with an arrow. The red triangle on the top left hand corner of node 1.3 indicates a marked node.
4.	Choose, as appropriate, either Compare with mark or Merge to mark from the right mouse menu.


Viewing object version event details

Related Topics

You can view details of all the events that have occurred for an object using the Version Event Viewer.  About

The Version Event Viewer can be run from any of the tools used for editing your objects.

Because the Version Event Viewer works independently of any workarea context, it can display event details for all versions of a single repository object.

Note:	The selected object must be under version control before you can view its details in the Version Event Viewer.

To view the version event details of an object:

1.	Select the object whose version events you want to view.

2.	Choose Version→View Version Events.

The version events for the selected object are displayed in the Version Event Viewer.

3.	You may wish to customize the details displayed to view events only between specified dates, and to rearrange the way in which report details are displayed.  How


Customizing the Version Event Viewer

Related Topics

Using the Version Event Viewer, you can view details of all the events that have occurred for an object.  About

You can customize the details displayed in the Version Event Viewer to:

•	view events only between specified dates; you can specify a start date, an end date, or both. If you do not set any dates, all events up to the last recorded event for the chosen object are displayed.

•	rearrange the way in which the report details are displayed; you can include or exclude details, as well as reorder and relocate details on the display.

•	exclude details of checkout events: if the object is currently checked out, you can choose whether or not to include the details of any checkout events in the most recent checkout.

Note:	Any changes you make to the details displayed are not reflected in the Version Event Viewer window until you click the Rescan button.

The following tasks assume that you have already displayed the Version Event Viewer.  How

To view events between specified dates:

1.	In the Version Event Viewer, click the Start date checkbox to activate the Start date editor.

2.	Click on the part of the date or time you want to change.

3.	Use the up and down arrows to change the selection.

4.	Click the End date checkbox to activate the End date editor.

5.	Click on the part of the date or time you want to change.

6.	Use the up and down arrows to change the selection.

7.	Click Rescan to refresh the display with the chosen details.

To rearrange the report display:

The display list provides a list of the details currently displayed in the report, including the order in which they are displayed and whether they appear in the left or right columns. The drop-down list lists all possible details for the event.

1.	Rearrange the details of the report as required:

•	To add any additional details to the report, select the chosen detail from the drop-down list and click Add.

•	To remove any details, select the detail from this display list and click Remove.

•	To reorder any details, select the detail from the display list and click Higher or Lower as appropriate.

•	To reposition any details between columns, select the detail from the display and click Move Left or Move Right as appropriate.

2.	Click Rescan to refresh the display with the chosen details.

Note: 	It is suggested that notes are displayed at the end of each event detail as they may require several lines.

To exclude checkout event details from the view:

1.	Click the Exclude Checkouts checkbox.

2.	Click Rescan to refresh the display.

Note:	Checkout details are overwritten each time the object is checked in, so checkout details are only shown if the object currently has a checked-out version.


Creating a branch

Related Topics

Creating a branch involves:

•	identifying an existing branch label or creating a new branch label

•	assigning the branch label as your default checkin branch

Branch labels can only be created by users with the Manage Branch Label system privilege.

Branch labels can only be assigned as a default checkin branch if the repository policy for branching is set to automatic branching. Repository policies can be changed only by users with the Set Policy system privilege.  How

You can create a branch using the Repository Object Navigator.

When a branch has been created and assigned as the default working branch, all subsequent checkins in the selected workarea will check in to the new default branch.

To create a new branch label:

1.	In the Repository Object Navigator, choose Version→Edit Branch Labels.

2.	In the Branch Labels dialog box click Add.

3.	In the Add Branch Label dialog box, enter the label name and any notes you want to associate with this label.

To assign a branch as your default checkin branch:

1.	In the Repository Object Navigator, choose Edit→Edit Workarea to display the Edit Workarea wizard.

2.	On the Checkin branch page of the wizard, select the required branch as the default checkin branch.

3.	Click Finish.

Note:	If a new object is created and checked in for the first time to a branch other than MAIN, two versions are created, one on MAIN and the other on the specified alternative branch.


Setting policies

Related Topics

You can set repository-wide options that control the policy used for certain aspects of:

•	version control (automatic branching, version labeling, locking on checkout)

•	file naming (case sensitivity)

•	object dependencies

Policies can be set only by a user with the Set Policy system privilege. About

To set a policy:

1.	In the Repository Object Navigator, choose Version→Edit Policies.

2.	In the Edit Policies dialog box, select the option for the policy you require.


Working with branch labels

Related Topics

Branch labels enable you to identify additional branches where object versions can be developed in parallel with, or as an alternative to, versions on the MAIN branch. Branch labels are managed using the Repository Object Navigator.

You may wish to:

•	add a new label

•	edit an existing label

•	delete a label

•	display details of branch label usage

Only users with the Manage Branch Label system privilege can create, update and delete branch labels.

Note:	You cannot edit or delete a branch label if it is currently being used by any object version.

To create a new branch label:

1.	In the Repository Object Navigator, choose Version→Edit Branch Labels.

2.	In the Branch Labels dialog box click Add.

3.	In the Add Branch Label dialog box, enter the label name and any notes you want to associate with this label.

To edit an existing branch label:

1.	In the Repository Object Navigator, choose Version→Edit Branch Labels.

2.	In the Branch Labels dialog box select the label you want to edit.

3.	Click Edit.

4.	In the Edit Branch Label dialog box, edit the label name and any notes associated with this label.

To delete a branch label:

1.	In the Repository Object Navigator, choose Version→Edit Branch Labels.

2.	In the Branch Labels dialog box select the label you want to delete.

3.	Click Delete.

To display details of branch label usage:

1.	In the Repository Object Navigator, choose Version→Edit Branch Labels.

2.	In the Branch Labels dialog box select the branch label for which you want to view a list of the objects associated with the selected branch.

3.	Click Used by.


Customizing the Version History Viewer

Related Topics

The Version History Viewer enables you to view the version history of an object displayed in a graphical representation.  About

Using the Version History Viewer, you can also view the following additional information about an object version:

•	checkout properties

•	version properties

•	a summary list of configurations containing the version

•	a summary list of workareas containing the version

For ease of use and clarity, you may wish to customize the display of the Version History Viewer to:

•	show or hide notes

•	show or hide the status panel

•	show or hide insignificant versions

•	show or hide successors

•	change the colors of nodes

The following tasks assume that you have already displayed the Version History Viewer.  How

To view additional information about an object version:

1.	In the Version History Viewer, select the object version node for which you want to view additional information.

2.	According to the information required, do one or more of the following:

•	To view checkout properties of an object version, choose Checkout Properties→<workarea/version name> from the right mouse menu.

<workarea/version name> lists all the versions of the object that are currently checked out in any workarea. You can view the checkout properties for any version of the object that is checked out, regardless of the workarea in which it is checked out.

•	To view version properties of an object, click  [image] to display the Version Properties dialog box.

•	To view a summary list of the configurations that contain the object version, click  [image]  to display the Which configurations include this version dialog box.

•	To view a summary list of the workareas that contain the object version, click  [image]  to display the Which workareas include this version dialog box.

To show or hide notes:

Note:	Notes are displayed in abbreviated form if they exceed 24 characters. Full details of the note can be viewed from the Version Properties dialog box.

•	To display the notes associated with all object versions, click

•	To display the notes associated with major notes, click

•	To hide all the notes in the display area, click

To show or hide the status panel:

Hiding the status panel increases the display area in the Version History Viewer.

•	To show or hide the status panel, click

To show or hide insignificant versions:

Insignificant versions include those that are not root or tip versions, are not branch parent versions, are not target or source versions in a merge operation, are not common ancestor versions, or are not the source of a checkout. Insignificant versions are often identified prior to being purged from a branch or from the entire version tree.  How

•	To show or hide insignificant versions, click the click

To show or hide successor nodes:

Hiding successor nodes temporarily removes nodes below the selected node on a branch, so reducing the amount of space required by the complete version tree.

1.	Select the node whose successors you want to hide or show.

2.	To show successor nodes, choose Show Successors from the right mouse menu.

To hide successor nodes, choose Hide Successors from the right mouse menu.

To change the colors of nodes:

The default node colors for leaf nodes, major nodes and checked-out nodes can be changed according to your personal preference.  About

1.	Click the Node color selector on the toolbar.

2.	To use a selected color to highlight a node type, ensure that the checkbox for the required node is selected.

Tip:	If you do not want to highlight a node type, ensure that the checkbox for the required node is not selected.

3.	To change the color of a node type, click the colored button for that node type.

4.	In the color selector palette, change the color of the selected node type.

Note: 	Nodes with hidden successors are shown in gray. This color cannot be changed.


Undoing a checkout

Related Topics

Undoing a checkout reverts the object to the state it was in prior to being checked out. Any changes made to the object since it was checked out are lost.  About

You can undo a checkout from:

•	the Version History Viewer

•	the Repository Object Navigator

•	the List checkouts dialog box

To undo a checkout from the Version History Viewer:

1.	Select the object for which you want to undo the checkout.

2.	Choose Version→View Version History.

3.	Select the checked-out version node.

4.	Click

Tip:	You can also undo a checkout by choosing Undo Checkout→<workarea/version name> from the right mouse button menu. This feature also enables you to view a list of all the versions of the object that are currently checked out in a workarea. You can undo the checkout only of the version in your workarea.

To undo a checkout from the Repository Object Navigator:

1.	In the Repository Object Navigator, select the object for which you want to undo the checkout.

2.	Choose Version→Undo Checkout.

To undo a checkout from the List checkouts dialog box:

1.	In the Repository Object Navigator, choose Version→List Checkouts to display the List Checkouts: Criteria dialog box.

2.	Select Checked out objects.

For ease of viewing it is recommended that Non versioned objects and Non repository files should not be selected.

3.	Click OK to display the List Checkouts dialog box.

4.	Select one or more checked-out objects for which you want to undo the checkout.

5.	Click Undo Checkout.


Purging object versions

Related Topics

You can purge a specific version, insignificant versions, or all versions, of a repository object.  About

To purge versions of an object:

1.	In the Repository Object Navigator, select the object you want to purge .

2.	Choose Version→Purge Versions.

The Purge Versions dialog box is displayed.

3.	Specify the scope of the purge operation:

•	To purge a specific version of a selected object, select Purge specific version.

The version of the object displayed in the Repository Object Navigator is the version selected for purging by default. You can select an alternative version to purge.

•	To purge all insignificant versions from a selected object, select Purge all insignificant versions.

•	To purge all insignificant versions from a particular branch, select Purge insignificant versions on branch, and select the branch you want to purge.

•	To purge all versions of an object and remove the entire object from the repository, select Purge all versions.

4.	Click Purge.


Viewing object version details

Using the Repository Object Navigator, you can view the details of the contents of a selected object version. For workareas, containers, configurations and other repository objects, you can display:

•	general details about the contents (including date and user details for creation and last modification, and number of times modified)

•	version details about the contents (including branch name, version number and label, status, rule, date and user details for last checkout)

The version of the selected object for which the details are displayed is the version that is currently visible in your workarea.

To view object version details:

1.	In the Repository Object Navigator, select the object version for which you want to view details of its contents (for example, select a container name to see details of objects in that container).

2.	Choose Version→View Version Details.

3.	(Optional)  Prevent the Details window from being hidden behind any of the currently open windows, by choosing Window→Arrange Windows.

4.	In the Details window, move to the desired point in the repository hierarchy if it is not already displayed.

To move down the hierarchy, double-click an item name.

To move up one level in the hierarchy, click  [image] .

5.	Determine how the objects are displayed and what categories of information are displayed, as follows:

•	to display the names as a multi-column list, click

•	to display the names as a single-column list, click

•	to display general details, click

•	to display version details, click

6.	If required, turn on or off the synchronization of the Details window with the Navigator window. When synchronized, navigating up or down the repository hierarchy in one window is duplicated in the other window.

•	to turn off synchronization with the Navigator window, click

•	to turn on synchronization with the Navigator window, click


Customizing the Compare window

Related Topics

When using the Compare window you can:

•	define the contents displayed in the window by choosing to display either just the differences or the entire contents of both object versions. The window defaults to displaying the entire contents of both object versions.

•	navigate through the differences in the window

•	customize the colors used in the window for highlighting differences

To define the contents displayed in the window:

•	Click  [image]  to switch between displaying only the differences and displaying the entire contents of both object versions.

To navigate through the differences in the window:

•	Click  [image]  to go to the next difference.

•	Click  [image]  to go back to the previous difference.

To customize the colors used in the window for highlighting differences:

1.	Click the button representing the difference (Added, Deleted, Updated) for which you want to change the color.

The color palette is launched.

2.	Select the required color from the palette.


Customizing the Merge window

Related Topics

When using the Merge window you can:

•	display or hide details

•	navigate through the details of the Merge window

•	customize the colors used in the window for the ancestor, source and target object versions

To display or hide details:

Some items shown in the Merge window may be compound items containing one or more comparison units.

•	To expand items, click the + button

•	To contract items, click the - button

To navigate through the details of the Merge window:

•	Click [image] to go to the next difference

•	Click [image] to go back to the previous difference

•	Click [image] to go to the next conflict

•	Click [image] to go back to the previous conflict

To customize the colors used for the ancestor, source and target object versions:

1.	Click the button representing the object for which you want to change the color.

The color palette is launched.

2. 	Select the required color from the palette.


Editing files from the Merge window

Related Topics

When merging files, you can edit the text in the files directly from the Merge window. The edits you make go forward to the result; the previous version of the target, the source and the common ancestor are not affected by the edits.

To edit lines in a file:

•	To edit a line, click in the line and use the arrow keys to move within the line

•	To insert a new line, press Enter

•	To cut selected text, press Ctrl + X

•	To insert text from the clipboard, press Ctrl + V

•	To copy selected text, press Ctrl + C


Setting the display format for object versions

Related Topics

For all objects that are under version control you can determine the display format of the object versions when used in all the repository tools.

Two formats are available:

•	Version label: the version label assigned to the object version. A version label is a string that uniquely identifies each version of an object. Version labels may be created automatically by the repository or may be defined by the user, according to the repository policy set for version labeling.

•	Branch; Version number: the branch on which the object version is located, followed by the version number of the object.

To display object versions with their version labels:

1.	In the Repository Object Navigator, choose Options→General Settings.

2.	In the General Settings dialog box, select the Version Label property.

To display object versions with their branches and version numbers:

1.	In the Repository Object Navigator, choose Options→General Settings.

2.	In the General Settings dialog box, select the Branch; Version Number property.