Sun WorkShop TeamWare User's Guide |
Sun WorkShop TeamWare Architecture
This chapter describes the underlying files that Sun WorkShop TeamWare uses to track workspaces and files. It also describes the ways Configuring manipulates SCCS history files when you copy files between workspaces and resolve conflicts.
This chapter discusses the following topics:
- Workspace Metadata Directory
- Configuring Defaults Files
- How Configuring Merges Files
- About SCCS Mergeable IDs
Workspace Metadata Directory
A Configuring workspace is a directory hierarchy that contains a directory named
Codemgr_wsdata
in its root directory. The Configuring program stores data (metadata) about that workspace inCodemgr_wsdata
. Configuring commands use the presence or absence of this directory to determine whether a directory is a workspace.Configuring provides the tools necessary to maintain the information kept in the
Codemgr_wsdata
directory. Although not recommended, it might be necessary to modify certain files manually; however, you must be very careful to preserve the format of each file you edit. TABLE 12-1 briefly describes each of the files and directories contained in theCodemgr_wsdata
directory. Information regarding the format of these files is available in theman(4)
page for each file.
TABLE 12-1 Contents of the Codemgr_wsdata
Metadata Directoryaccess_control
Contains information that controls which users are allowed to execute Configuring transactions and commands for a given workspace. When workspaces are created, a default access control file is also created. See Chapter 4 and The access_control File. args
Contains a list of file, directory, and FLP arguments and is maintained by the Configuring, Bringover, and Putback transaction commands. Initially, the args
file contains the arguments specified when the workspace was created. If you explicitly specify arguments during subsequent Bringover or Putback transactions, the commands determine if the new arguments are more encompassing than the arguments already in theargs
file; if they are, the new arguments replace the old. See Creating Customized Bringover/Putback File Lists.backup/
Stores information that Configuring uses to "undo" a Bringover or Putback transaction. See Undoing Changes to a Workspace. children
Contains a list of the workspace's child workspaces. The names of child workspaces are entered into the workspace's children
file during the Bringover Create transaction. Configuring consults this file to obtain the list of child workspaces. When you delete, move, or reparent a workspace, Configuring updates thechildren
file in its parent.conflicts
Contains a list of files in that workspace that are currently in conflict. See Chapter 6 for more information about conflicts and how to resolve them. description
Contains a descriptive name and detailed description of a TeamWare workspace created by the user. See Giving a Workspace a Descriptive Name. Freezepoints/
Created when you set up auto-freezepoints. See Automatically Generating Freezepoints. history
An historical log of transactions and updated files that affect a workspace. See Viewing Workspace History for more information. locks
To assure consistency, Configuring locks workspaces during Bringover, Putback, and Undo transactions. Locks are recorded in the locks
file in each workspace; Configuring checks that file before acting in a workspace. See Removing Workspace Locks.nametable
Contains a table of SCCS file names (path names relative to that workspace) and a unique number represented as four 32-bit hexadecimal words. Each entry in the table is terminated by a newline character. The nametable
file is used by Configuring during bringover and putback to accelerate the processing of files that have been renamed. If this file is not available, Configuring rebuilds it automatically during the next Putback or Bringover transaction. See Renaming, Moving, or Deleting Files.notification
Permits Configuring to detect events that involve that workspace and to send email in response to the event. See Notifying Users of Transactions. parent
The parent
file contains the path name of the workspace's parent workspace and is created by the Bringover Create transaction, or by thereparent
command if the workspace was originally created with thecreate workspace
command (and thus had no parent). Configuring consults this file to determine a workspace's parent. When you delete, move, or reparent a workspace, Configuring updates theparent
file in its children.putback.cmt
A cache of the text of the comment from the last blocked Putback transaction. Configuring caches the comment in putback.cmt
so that you can retrieve the original text when you re-execute the transaction.
Configuring Defaults Files
When you change Configuring behavior using the Tool Properties window, click the Apply button to preserve the changes in runtime configuration files in your home directory. The runtime configuration files are consulted by Configuring when it starts; your changes are used as the default values.
Changes made in the Configuring and Bringover/Putback panes of the Tool Properties window are written to the file
~/.codemgrtoolrc
. This file is an XWindows resource file.Changes made in the Resolve pane of the Tool Properties window are written to the runtime configuration file
~/.codemgr_resrc
.You can also control which workspaces are loaded by default using environment variables (see Configuring Environment Variables). You can save a default list of files to bringover/putback (see Generating a Customized List of Files).
The
access_control
FileChapter 4 introduces the concept of controlling who can perform which transactions on a workspace. When you set permissions in the Access Control tab (under Workspace Properties), TeamWare writes the permission in the
access_control
file. TABLE 12-2 shows the default contents ofaccess_control
after you create a workspace.
You can manually edit the
access_control
file to control which users have access to a workspace. TABLE 12-3 shows all of the value types you can specify to control access to your workspaces and what the entries mean.
How Configuring Merges Files
This discussion assumes that you are familiar with SCCS, including the concept of branching. Branching is defined in How To Read a File's History: Deltas, Branches and Versions. SCCS is described in detail in the Solaris Programming Utilities manual.
When considering Bringover and Putback transactions, remember that source files are derived from SCCS deltas and are identified by SCCS delta IDs (SIDs). When a file is copied by either a Putback or Bringover transaction, the Configuring program must manipulate the file's SCCS history file (also known as the "s-dot-file").
When a file is copied (using a Bringover or Putback transaction) from a source workspace to a destination workspace, it appears that a single file has been transferred. In fact, all of the SCCS information for that file (deltas, comments, and so on) must be merged into the destination SCCS history file. By merging the information from the source into the destination history file, the current version (delta) can be derived, and the file's entire delta and comment history are available. The exception is when the file does not exist in the destination workspace. In this case, the entire history file is copied from the source workspace to the destination workspace.
Merging Files That Do Not Conflict
If the file in the destination workspace is being updated (the file has changed in the source of a Bringover or Putback transaction and has not changed in the destination), the new deltas from the destination are added to the history file in the destination. SCCS history files are merged in this case (rather than the source history file being copied over the destination history file) to prevent administrative information (for example, flags and access lists) stored in the destination history file from being overwritten.
To accomplish the merger, the Configuring program determines where the delta histories diverge and adds (to the destination workspace) only the deltas that were created in the source workspace since they diverged. To determine where the histories diverge, the Configuring program compares the delta tables in both the parent and child history files; information used in this comparison includes comments and data, such as who created the delta and when.
FIGURE 12-1 contains an example of a Putback transaction where the Configuring program adds deltas 1.3 and 1.4 from the child workspace to the SCCS history file in the parent.
FIGURE 12-1 Updating a File in the Destination Workspace That Has Not ChangedMerging Files That Conflict
When you propagate files between parent and child workspaces, both the version of the file from the parent and the version in your child often change since they were last updated. When that is the case, the parent and child versions of the file are in conflict.
When file contents conflict, Configuring helps you to resolve the potentially conflicting changes that were made to the file and preserves the file's delta, administrative, and comment history. Configuring merges the SCCS deltas from the parent into the history file in the child. Configuring's Resolve transaction is then used to resolve the conflict in the child. For details on resolving conflicts, see Resolving Differences.
How Merging Tracks Deltas
This merge example involves an integration workspace and two child workspaces owned by different developers, Ian and Ramona. The developers bring over copies of the same file from the integration workspace, and independently change the file. The illustrations show how the SCCS history file is manipulated when conflicts occur and when they are resolved. Some notes regarding the following figures:
- The default delta (the point at which the next delta is added to the SCCS delta tree) is identified by an unattached descending line.
- You can use Versioning to graphically display SCCS delta trees in much the same way they are depicted here.
Both Ian and Ramona copy the same file from the integration workspace with the Bringover transaction. The file is new in both workspaces, so the SCCS history file is copied to both. Integration Workspace represents the parent workspace that both Ian and Ramona use.
Ramona makes changes to the file, creating two new deltas: 1.3 and 1.4, and then puts the file back into the integration workspace (with the Putback transaction). Configuring appends the two new deltas to the parent SCCS delta tree.
Rather than replacing the destination workspace version of the SCCS history file with the source's version, the new deltas are added to the destination SCCS history file to preserve administrative information such as access lists.
In the meantime, Ian also changes the file (creating three new deltas: 1.3, 1.4, and 1.5) and now attempts to put back the file into the integration workspace.
Configuring blocks the Ian's Putback transaction of because the files are in conflict. Ramona's changes that she put back would be overwritten. Ian must first incorporate the changes made by Ramona into his work.
Ian brings over the file that now contains the changes made by Ramona into his workspace from the integration workspace. The deltas that Ramona created are added into the child SCCS history file by Configuring.
The delta tree brought down from the parent is unchanged in the child. The new deltas created in the child are attached as an SCCS branch to the last delta that the child and parent had in common; the deltas from the child are assigned new SIDs accordingly. The deltas are renumbered using the SCCS branch-numbering algorithm that derives the SID from the point at which it branches. In this case, the branch is attached to SID 1.2; the first delta is renumbered to 1.2.1.1. The last delta created in the child (1.2.1.3, formerly 1.5) is still the default delta. Therefore, any new deltas that Ian creates in the child before the conflict is resolved are added to the child line of work, and not the trunk (the parent line of work).
Ian resolves the conflict in his workspace using the Resolve transaction (see Resolving Differences for details regarding conflict resolution). Ian uses the Resolve transaction to help him decide how to merge the versions of the file represented by SIDs 1.2.1.3 and 1.4. When he commits the changes, the Resolve transaction places the newly merged contents into a new delta 1.5:
- The new delta, 1.5, is contained in a circle because Ian created it.
- The newly created delta is now the default location for any new work Ian creates.
With the conflict resolved, Ian puts back the file into the integration workspace. The branch and the newly created delta are added to the SCCS history file in the integration workspace.
Ramona makes another change to the file in her workspace, creating delta 1.5. She attempts to put back the new work to the integration workspace, but the Putback transaction is blocked because it conflicts with the newly merged delta 1.5 that Ian had put back.
Ramona brings over the changed file into her workspace where its deltas are added into the child SCCS history file and renumbered by Configuring.
As in the previous case, Configuring appends the delta that Ramona created to the last common delta on the delta tree trunk as a branch and renumbers it appropriately. 1.5 becomes 1.4.1.1. 1.4.1.1 remains the default delta. Any new deltas created in the child before the conflict is resolved will be added to the branch.
Using the Resolve transaction, Ramona resolves the conflict merging the differences between 1.5 and 1.4.1.1 to create the new delta 1.6:
- The newly created merged contents are added as a new delta to the parent delta 1.6.
- The new delta is owned by Ramona, who owns the workspace.
- The new delta becomes the default delta; therefore, new work in the child will now be added beneath it.
This merge example has shown what happens when you have an integration workspace and two child workspaces owned by different developers. The developers bring over copies of the same file from the integration workspace and independently change the file. When they attempt to put their changes back, conflicts occur. Configuring manages deltas to ensure that no one's changes are overwritten and manipulates the SCCS history file so that the file history is accurate and complete.
About SCCS Mergeable IDs
This section explains why SCCS Mergeable IDs (SMIDs) are necessary, how to translate SCCS delta IDS (SIDs) to SMIDs, and how to translate SMIDs to SIDs.
The use of SMIDs ensures that every delta is uniquely identifiable, even if its SID is changed. A SMID is a number generated using the Xerox Secure Hash Function. When you use Freezepointing to create a freezepoint file, it calculates the SMID for both the current delta and the root delta in the SCCS history file. Using both of these values, Freezepointing can identify a delta in a file even if its SID has been changed.
Why SMIDs are Necessary
When Configuring encounters a file conflict during a Bringover Update transaction (file is changed in both the parent and child workspaces), it merges the new deltas from the parent workspace into the SCCS history file in the child. When this merge occurs, the deltas that were created in the child are moved to an SCCS branch off of the delta that both deltas have in common (common ancestor).
When Configuring relocates the child deltas to a branch, it changes their SID. If SIDS were used in freezepoint files to identify deltas, this relocation would invalidate the information contained in the freezepoint file. For that reason, SIDs cannot be used to identify deltas after conflicting SCCS histories have been merged.
SMID/SID Translation
You can translate SMIDs into SIDs and SIDs into SMIDs using the
freezept
sid
andfreezept smid
commands. This is useful if you want to write your own scripts or programs to track deltas.Translating SIDs to SMIDs
Use the
freezept
smid
command to translate SIDs to SMIDs. The syntax is:
freezept smid
[-w
workspace] [-r
SID] [-a
] file
- Use the
-r
option to specify the SID (in file file) for which you want to calculate a SMID.- Use the
-a
option to calculate a SMID for all of the SIDS in file.- For convenience, you can use the
-s
option to specify a directory from which file is relative.Examples
example%freezept smid -r 1.38 module.c
SID 1.38 = SMID "f5b67794 705f0768 a89b1f4 588de104"
Translating SMIDS to SIDS
Use the
freezept
sid
command to translate SMIDs to SIDs. The syntax is:
freezept sid
[-w
workspace] [-m
"SMID"] [-a
] file
- Use the
-m
option to specify the SMID (in file file) for which you want to calculate a SID.- Use the
-a
option to calculate a SID for all of the deltas in file.- For convenience, you can use the
-s
option to specify a directory from which file is relative.
Note Because the SMID contains white space, you must enclose it within quotation marks.
Examples
example%freezept sid -m "64fdd0df de9d7dd de75812 23da96aa" module.c
SMID "64fdd0df de9d7dd de75812 23da96aa" = SID 1.36
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |