Files

To place a file under version control, it must be added to a folder in a StarTeam project view, which stores a copy of the file in the StarTeam repository. After the file has been added to StarTeam, you and other members of your team can check it out, revise it, and check in new revisions, while StarTeam maintains information on all revisions of the file. Note that all check-ins in StarTeam are atomic.

When checking out a file revision, you should verify that you have the tip or latest version of the file. Doing this ensures that the file you see contains the latest changes. If you intend to modify the file, you should check it out with an exclusive lock, to indicate to others that you are working on it.

When you check a file in, StarTeam records the file changes as a new revision. As part of the check-in process, you can remove the lock, notifying others that the file is available, or maintain the lock, showing that you intend to continue working on the file. If two team members change the same text file simultaneously or if one member changes an outdated file, StarTeam contains a merge option that allows the file changes to be combined so that no work is lost. In such cases, StarTeam assigns a Merge status to the file.

Note: The SDK, StarTeam Server, and most clients support files larger than 4 GB. If you plan on taking advantage of large file support, you should upgrade all users to the current StarTeam version. Large file sizes are not compatible with older StarTeam versions.

Files Under Version Control

If a file resides in the working folder of an application folder, you can add that file to the application folder. This operation places that file under version control. A copy of the working file becomes the first revision of that file stored in the repository. If the working file is deleted later, the data is not lost because a copy exists in the repository. The application creates a new revision of this file in the repository every time you check the file in.

Every time you check a file revision out, its contents are copied to a working folder. Checking out a revision also ensures that you have the tip or a specific revision to work on. For example, you may need a team member’s most recent changes to a file, or you may have deleted the working file from your hard drive and now need another copy.

The application enables you to label the tip revisions of every item within a view. For example, when the project reaches a particular milestone (such as beta), you might give the view’s items a label, called a view label. Then you can configure the view to return to the way it was at the time the label was applied, check out revisions as a group using that label, create a new view based on the label, or assign the label to a promotion state.

The application also provides revision or version labels. You can label one or more revisions as you check them in or by applying the label to each of the revisions using the Labels command on the File menu. StarTeam makes it easy to check out those files as a group using the label. A file revision can have any number of labels. However, no two revisions of the same file in the same view can have the same label.

Recommendations for Working with Files Under Version Control

Here are some recommendations about using files under version control:

To let other team members know that you intend to make changes to a file, change the lock status to exclusive as part of the check-out procedure.
As part of the check-in process, you can notify others both that you are finished making your changes to the file and that it is available for them to check out by removing the lock status.
If you intend to continue making changes to the file but still want to check it in for backup purposes, keep the file locked.
If two team members change the same text file simultaneously or if one member changes an outdated file, you can use the merge option to combine the changes in these files so no work is lost. In such cases, the application gives the file a Merge status.
To prevent yourself from changing a file that you have not locked, select the Mark Unlocked Working Files Read-only personal option. Then, if you check out a file that you have not locked, the working copy becomes read-only.