The Keep command creates a new version A particular revision of an element, reflecting a content change (files only) or a namespace change (files and directories). All versions are originally created in workspaces, and can subsequently be promoted to dynamic streams. The original (workspace) version is termed a 'real version'. Each promotion to a dynamic stream creates a 'virtual version', which serves as an alias for (pointer to) the original real version. of one or more file elements A file or directory that is under AccuRev version control. See version.. Both the contents of the version and its identity are stored permanently in the AccuRev repository The directory tree that stores all software configuration management data managed by AccuRev. This data is maintained by the AccuRev Server, responding to requests made through AccuRev client programs. Users never manipulate the repository directly.. For each file you Keep:
AccuRev copies the contents of the file currently in your workspace tree The ordinary directory tree, located in the user's disk storage, in which the user performs development tasks and executes AccuRev commands. to the associated depot in the repository.
AccuRev assigns a version-ID The unique identifier for a version, consisting of two parts: (1) the name or number of the workspace or stream in which the version was created; (2) an integer. Examples: talon_dvt_mary/14, 245\19. to the new version, consisting of the workspace's name and an integer. For example, the version-ID
talon_dvt_mary/17
... identifies the 17th version of the file element that was created in the workspace named talon_dvt_mary.
In the Details pane of a File Browser that is open on a workspace, select one or more file elements. Then:
Click the Keep toolbar button, or
Right-click the selection and choose Keep from the context menu.
The Keep dialog appears, which you use to complete the command.
The Keep dialog includes basic options (always visible) and advanced options (visibility controlled by a Basic/Advanced button).
Comment
You can enter a comment string in the text box. (AccuRev "seeds" the text box with your most recent Keep comment.) The comment string becomes a permanent annotation to the version you're creating.
AccuRev itself does not require a comment, but your organization can establish such a requirement by putting a trigger The AccuRev facility that enables user-defined procedures (trigger scripts) to be performed automatically before or after certain operations take place. on the Keep command.
Choose File Type
By default, AccuRev determines the element type for the newly created version automatically (text or binary). You can override the default by specifying either of these types or ptext (a variant of text). See AccuRev Element Types.
Choosing Enable File Locking places a lock A control on the file element, requiring (1) users must Anchor the file before editing it, and (2) if a user has Anchor'ed the file, users in sibling workspaces cannot Anchor or edit the file. on the element, to enforce serial development The practice of ensuring that multiple users do not work concurrently on the same version-controlled file. See parallel development. in sibling workspaces Two or more workspaces or streams that have the same parent stream. for that element. This ensures that users in sibling workspaces won't have to merge An operation that combines the contents of two versions (contributors) of the same element. To merge the contents of text files, AccuRev uses a '3-way merge' algorithm: it compares the two files line-by-line with a third file, the version that is the closest common ancestor of the other two. Merging of namespace changes also takes into account the closest common ancestor. their work on this element. The lock remains on the element until you (or someone else) changes this value to Disable File Locking in a subsequent Keep command. See File Locks.
The Keep command does the following:
A new version object is created in the workspace stream The private stream that is built into a workspace. All new versions of elements are originally created in workspaces; AccuRev records these versions in workspace streams.. It has a unique version-ID The unique identifier for a version, consisting of two parts: (1) the name or number of the workspace or stream in which the version was created; (2) an integer. Examples: talon_dvt_mary/14, 245\19., such as talon_dvt_mary/13 ("the 13th version of this element created in workspace talon_dvt_mary"). A version object is immutable, and cannot be removed from the repository. The version created by Keep is termed a real version A version of an element, created in some user’s workspace, recording a change to the contents and/or pathname of the element. See version, virtual version., because it represents an actual change to an element. [note ]
Preserves the contents of the new version
The contents of the new version are preserved permanently in the repository. AccuRev copies the file in your workspace tree The ordinary directory tree, located in the user’s disk storage, in which the user performs development tasks and executes AccuRev commands. to a container file The ordinary file, located in the file storage area of the AccuRev repository, that contains the permanent copy of a version created in a workspace with the keep command. in the depot. No AccuRev operation modifies or removes the container file (exception: archive An operation that transfers the storage files for one or more versions from a depot’s file storage area to its gateway area. After the archived storage files are copied to off-line storage, the disk storage within the gateway area can be reclaimed. command).
The file element gets the status flag (kept) in your workspace. It also gets the (member) flag, indicating that the element is active An element is said to be active in a workspace or stream if a new version of the element has been created there, and that version has not been either (1) promoted to the parent stream or (2) purged from the workspace or stream. See default group, backed, passive. in your workspace. (It's possible that the element already had one or both these status flags, from previous activity in your workspace.) If the element previously had (modified) status, this flag is removed.
Notes (click to view):
Content changes and namespace changes
The Keep command preserves content changes A change to the contents of a file element, recorded in a new version created with the Keep command. For a link element, a change to the target pathname is a content change. See namespace change. only, not namespace changes A change to the pathname of a file or directory element: either renaming the element in place or moving the element to a different location in the depot’s directory hierarchy.. Suppose you edit a file, so that it has (modified) status, then give it a new name with the Rename command. The new version that Rename creates does not record your content changes. The file will still have (modified) status until you preserve the contents changes with Keep.
There is no true "undo" operation in AccuRev version control, since that would violate the TimeSafe The aspect of AccuRev’s architecture that guarantees the reproducibility of any previous configuration of a stream, a depot, or the entire repository. principle. The Revert to Backed command provides a close approximation. If you want to "undo" some, but not all of several intermediate Keep's, perform a Revert to Backed command followed by a Send to Workspace of the intermediate version.