Creates a modifiable copy of a version
Product | Command Type |
---|---|
ClearCase | cleartool subcommand |
ClearCase LT | cleartool subcommand |
Attache | command |
Platform |
---|
UNIX |
Windows |
For one or more elements, the checkout command checks out a branch (typically, the most recent version on a branch). In most cases, this creates a writable copy of that version in the current view (the checked-out version), but see the CHECKING OUT A DO VERSION section. An appropriate message is displayed. For example:
Checked out "msg.c" from version "/main/bugfix/25"
If you are checking out in a UCM view, the view must be set to a UCM activity (see setactivity). Checked-out elements are added to the change set of the UCM activity you set.
In Attache, files checked-out successfully are downloaded to the workspace after the checkout command is executed remotely. If a local file exists, and is both writable and different from the checked-out version, the user is queried before the local file is overwritten, but the file is always checked out in the view. Checked-out directories are created locally if they do not already exist in the workspace. All downloaded files are made writable.
A checkout record is created; it can be listed with the lscheckout command:
cmd-context lsco msg.c
05-Aug.20:50 akp checkout version "msg.c" from \main\bugfix\25 (reserved)
If a view-private object already exists with the same name as an element being checked out, checkout responds as follows:
In a dynamic view, it displays this error message:
Not a vob object: pname
To check out the element, rename or remove the view-private object with the standard operating system command and enter the checkout command again.
In a snapshot view, the behavior is different for view-private directories and view-private files:
A view-private directory that corresponds to a directory in the VOB namespace is checked out. That is, checkout creates a checkout record in the VOB for the directory element. Any changes to the checked-out directory in the view are added to the VOB at checkin.
A view-private file with the same name as an element being checked out is treated as a hijacked file. checkout asks whether you want to use the file as the checked-out version; if you do not, the view-private file is renamed.
In Attache, checkout saves the private object in the view, not in the workspace.
Before using a command that changes the contents of a directory (mkelem, mkdir, rmname, ln, or mv), you must first check out the directory. Each of these commands appends an appropriate line to the directory's checkout comment. For example, using mkelem to create a new element within a directory adds a line like this one:
Added file element "wel.c".
A version can have at most one reserved checkout and any number of unreserved checkouts. Performing a reserved checkout (without using the -version option) guarantees you the right to create a successor to the version you checked out. If several users perform unreserved checkouts, any one of them (and only one) can create a successor version.
The predecessor version of your checked-out file may not be the latest on the branch from which you checked out your version; this situation can occur if the -version option or unreserved checkouts are used. In this case, you must merge from the latest version on the branch to your checked-out version before you can check in your version.
You can change the reserved state of a checked-out version with the reserve and unreserve commands.
If the VOB containing the element is replicated, the checkout command fails if you try to check out a branch mastered by a different replica:
cleartool checkout -nc file1.txt
cleartool: Error: Unable to perform operation "checkout" in replica
"lexington" of VOB "/vobs/dev".
cleartool: Error: Master replica of branch "/main" is "london".
cleartool: Error: Unable to check out "file1.txt".
If you need to do work on a branch mastered by another replica, you have two choices:
Request mastership of the branch and wait until the mastership is transferred to your current replica before checking out the branch.
Check out the branch and do your work while waiting for mastership to be transferred. You can request mastership before or after checking out the branch. To check out the branch, use checkout -unreserved -nmaster, which performs a nonmastered checkout. When the mastership of the branch is transferred to your current replica, you may have to perform a merge before checking in your work. Therefore, do not use this option if you cannot merge versions of the element (for example, if the versions are in binary format).
To request mastership, ask the administrator at the master replica to transfer mastership, or use the reqmaster command. Consult your ClearCase administrator to make sure mastership requests with reqmaster are enabled and that the replicas are at the correct feature level.
By default, the checkout command checks out these versions:
The most recent version on a branch, if you are using a dynamic view
The version currently loaded in the view, if you are using a snapshot view
To modify a different version, you can either use the -version option or create a subbranch at that version. (See the mkbranch reference page). Furthermore, from a single view, you can have only one checkout per element at a time.
NOTE: When working in a snapshot view, the only version of a directory element that can be checked out is the version currently loaded in the view. Therefore, the -version and -branch options will not work in this case.
When you use the -version option, you can specify the version either by setting your config spec to use that version, or by specifying a version-extended pathname as the pname argument. After you make your changes, you must merge from the latest version of the element before you can perform a checkin.
You can check out a version that your config spec does not currently specify, either by using the -branch option or by specifying a pname argument that is a branch pathname (for example, msg.c@@/main/rel4_bugfix). In such cases, a warning message appears:
cleartool: Warning: Version checked out is different from version previously selected by view.
(Dynamic view) If the version being checked out is a derived object (DO version), checkout attempts to winkin the DO to your view. If it cannot perform the winkin, it copies the DO's data instead. A winkin cannot be performed if you use the -out option to specify a destination in another VOB, or in a non-VOB location, such as /tmp.
See Building Software for additional information on the behavior of checked-out DO versions.
If the config spec specifies a version using a rule with a -mkbranch branch-type clause (see also config_spec), checkout works as follows:
Creates a branch of type branch-type.
Checks out (version 0 on) the new branch.
Except for some extra messages, the behavior is no different from an ordinary checkout. The checked-out version has the expected contents, because version 0 on the new branch has the same contents as the version at the branch point.
NOTE: (MultiSite sites) If the VOB is replicated, the current replica must master all the branch types specified in your config spec. Otherwise, auto-make-branch fails.
A config spec can include a cascade of auto-make-branch rules, causing checkout to create multiple branching levels at once. checkout keeps performing auto-make-branch until version 0 on the newly created branch is not selected by a rule with a -mkbranch clause. For example:
1 |
element * CHECKEDOUT |
2 |
element * .../br2/LATEST |
3 |
element * .../br1/LATEST -mkbranch br2 |
4 |
element * MYLABEL -mkbranch br1 |
5 |
element * /main/LATEST |
If you check out an element in a view that currently selects the version labeled MYLABEL:
A branch of type br1 is created at the MYLABEL version (Rule 4).
Rule 3 now selects the newly-created version .../br1/0, so a branch of type br2 is created at that version.
Version .../br1/br2/0 is checked out. The checked-out version has the same contents as the MYLABEL version, and is selected by Rule 1. When you edit and check in a new version, .../br1/br2/1, the view selects it with Rule 2.
Any checked-out file can be read, edited, and deleted like any ordinary file.
You have write permission on a checked-out file only if you have write permission on the set view's view storage directory. If you have write permission on the view storage directory for the view you are using, you have write permission on a checked-out file in that view.
The initial permissions on the checked-out file are determined by this algorithm:
Start with the permissions of the element itself. (See the mkelem and protect reference pages.)
Add a write permission wherever the element itself has a read permission (user, group, and/or other).
(UNIX) Subtract read, write, and/or execute permissions according to your current umask(1) value.
You can change the permissions of the checked-out file with the standard UNIX chmod(1) command or by changing the Windows file properties, but you must use the protect command to change the permissions of the element itself.
A checked-out file is a workspace-local object.
There may be no object in the view located at the pathname of the checked-out version. This can happen if any of these conditions are true:
You have deleted the file.
You renamed the file.
You used checkout -out to copy the checked-out version to another location.
You used checkout -ndata to create only a checkout record for the version.
A permission problem occurred and checkout was unable to write the file. In this case, cancel the checkout (use uncheckout), fix the permission problem, and check out the file again.
An OS-level listing command does not show the missing file, but the cleartool ls and Attache ls commands display the pathname of the checked-out version with the notation " checked out but removed."
Identities: You must have one of the following identities:
Element owner
Element group member
VOB owner
root (UNIX)
Member of the ClearCase group (ClearCase on Windows)
Local administrator of the ClearCase LT server host (ClearCase LT on Windows)
Additional restrictions on UNIX:
If the element's set-UID bit is set, only the element's owner, the VOB owner, or root can check out the version.
If the element's set-GID bit is set, only a member of the element's group, the VOB owner, or root can check out the version.
Locks: An error occurs if one or more of these objects are locked: VOB, element type, branch type, element, branch.
Mastership: (Replicated VOBs) Your current replica must master the branch you are checking out unless you use -unreserved -nmaster.
RESERVED AND UNRESERVED CHECKOUTS. Default: checkout reserves the branch unless a different default has been specified in profile_ccase.
CREATION OF CHECKED-OUT VERSION IN VIEW. Default: (file elements) Creates in the view:
A view-private file for the version being checked out with the same pathname as the element (dynamic view).
A modifiable copy of the version being checked out with the same pathname as the element (snapshot view).
Attache downloads a copy of that file to the workspace.
EXCEPTION: (Dynamic views) If the version being checked out is a derived object, it is winked in to the view.
checkedout but removed
.checked out but removed
. This option is useful for checking out files that will be completely overwritten (for example, staged binaries or other files that are copied into place).PRESERVING MODIFICATION TIME. Default: In a dynamic view, checkout resets the file's modification time to the checkout time. In a snapshot view, checkout preserves the file's modification time.
NON-STANDARD CHECKOUTS. Default: If pname specifies a particular branch, check out that branch, that is, the latest version on the branch. Otherwise, do the following:
In a dynamic view, check out the latest version on the branch.
In a snapshot view, check out the version that is currently in the view.
checkout creates a copy of each checked-out version and names it pname.
SUPPRESSING WARNING MESSAGES Default: Warning messages are displayed.
EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by your .clearcase_profile file (default: -cqe). See the comments reference page. Comments can be edited with chevent.
QUERYING FOR THE RESOLUTION OF CHECKOUT PROBLEMS. Default: No querying.
ELEMENT ARGUMENT. Default: None.
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.
Check out the currently selected version of element hello.c, with no comment.
cmd-context checkout -nc hello.c
Checked out "hello.c" from version "/main/3".
Check out the latest version on the rel2_bugfix branch of file msg.c, to another file name.
cmd-context checkout -nc -branch \main\rel2_bugfix -out msg_test.c msg.c
Checked out "msg.c" from version "\main\rel2_bugfix\1".
cmd-context ls msg_test.c msg.c
msg_test.c
msg.c@@\main\rel2_bugfix\CHECKEDOUT from \main\rel2_bugfix\1 [checked out
but removed]
(ClearCase and ClearCase LT) Check out the latest version on the rel2_bugfix branch of file msg.c, using an extended pathname to indicate the branch. This command checks out the same version as the preceding example.
cmd-context checkout -nc msg.c@@/main/rel2_bugfix
Checked out "msg.c" from version "/main/rel2_bugfix/1".
Check out an old version of the file hello.h, using an extended pathname to indicate the version. (Before you check in your revised version, you must perform a merge.)
cmd-context checkout -c "attempt fix of old bug" -version hello.h@@\main\1
Checked out "hello.h" from version "\main\1".
Perform an unreserved checkout of element hello.h. Provide a comment on the command line.
cmd-context checkout -c "modify local defines"-unreserved hello.h
Checked out "hello.h" from version "/main/2"
Check out hello.c. Then, change your mind and cancel the checkout, removing the view-private copy.
cmd-context checkout -nc hello.c
Checked out "hello.c" from version "\main\1".
cmd-context uncheckout -rm hello.c
Checkout cancelled for "hello.c".
checkin, config_spec, lscheckout, merge, profile_ccase, reserve, uncheckout, unreserve
Feedback on the documentation in this site? We welcome any comments!
Copyright © 2001 by Rational Software Corporation. All rights reserved. |