checkout

Creates a modifiable copy of a version

Applicability

Product

Command type

ClearCase®

cleartool subcommand
ClearCase Remote Client rcleartool subcommand

Platform

UNIX
Linux

Windows
Parent topic: Cleartool subcommands for base ClearCase and UCM
Parent topic: Alphabetical list of all commands
Parent topic: Rational ClearCase command reference

Synopsis

Description

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 section Checking out a DO version. 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.

A checkout record is created; it can be listed with the lscheckout command:

cmd-context lsco msg.c
—08-05T20:50 akp checkout version "msg.c" from \main\bugfix\25 (reserved)

If an existing view-private object has the same name as an element being checked out, checkout responds as follows:

You must check out a directory before you use a command that changes its contents (mkelem, mkdir, rmname, ln, or mv). 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".

Reserved and unreserved checkouts

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 those users (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.

MultiSite: Checking out a branch mastered at remote site when SRFM is not enabled

If the VOB that contains the element is replicated, and synchronous request for mastership (SRFM) is not enabled, then the checkout command fails if you try to check out a branch mastered by a remote 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".

In this case, if you need to work on a branch mastered by another replica, you can

  • Request mastership of the branch and wait until the mastership is transferred to your local replica before you check 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.

MultiSite: Checking out a branch mastered at a remote site when SRFM is enabled

If synchronous request for mastership (SRFM) has been enabled, checkout operations on a remotely mastered branch can proceed before branch mastership is acquired. The command checkout –srfm issues a request for mastership of a branch synchronously with the checkout operation. The state of such a checkout is in the pending reserved state and you can edit the element immediately. However, you cannot check in a new version until the replica acquires mastership of the branch.

You cannot use checkout -srfm to check out an element in these circumstances:
  • The element is a UCM object
  • The view is a snapshot view
  • The view is a dynamic view that specifies an auto-make-branch rule
To cancel an SRFM checkout, use uncheckout –nsrfm.

Nonstandard checkouts

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 you work 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 do not work.

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 path name 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 path name (for example, msg.c@@/main/rel4_bugfix). In such cases, a warning message is displayed:

cleartool: Warning: Version checked out is different from version
previously selected by view.

Checking out a DO version

(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.

For more information about the behavior of checked-out DO versions, see the IBM Rational ClearCase Guide to Building Software.

Auto-make-branch

If the config spec specifies a version using a rule with a –mkbranch branch-type clause (see also config_spec), checkout works as follows:

  1. Creates a branch of type branch-type.
  2. 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.

Multiple-level auto-make-branch

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:

element * CHECKEDOUT
element * .../br2/LATEST
element * .../br1/LATEST -mkbranch br2
element * MYLABEL -mkbranch br1
element * /main/LATEST

If you check out an element in a view that currently selects the version labeled MYLABEL:

  1. A branch of type br1 is created at the MYLABEL version, following the the fourth rule.
  2. The third rule then selects the newly created version .../br1/0, so a branch of type br2 is created at that version.
  3. Version .../br1/br2/0 is checked out. The checked-out version has the same contents as the MYLABEL version and is selected by the first rule. When you edit and check in a new version, .../br1/br2/1, the view selects it with the second rule.

Checked-out files

Any checked-out file can be read, edited, and deleted like any ordinary file.

Dynamic views

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.

Snapshot views

The initial permissions on the checked-out file are determined by this algorithm:

  1. Start with the permissions of the element itself. (See the mkelem and protect reference pages.)
  2. Add a write permission when the element itself has a read permission (user, group, and/or other).
  3. (UNIX and Linux) 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 or Linux command chmod(1) or by changing the Windows file properties, but you must use the protect command to change the permissions of the element itself.

Checked-out but removed files

There may be no object in the view located at the path name 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 command displays the path name of the checked-out version with the notation checked out but removed.

Restrictions

ACL authorization

If ACLs are enabled, the principal must have the following permissions:
  • read-info on VOB object
  • mod-checkout on element

Non-ACL authorization

You must have one of the following identities:

  • Element owner
  • Element group member
  • VOB owner
  • root (UNIX and Linux)
  • Member of the ClearCase administrators group (ClearCase on Windows)

Additional restrictions on UNIX and Linux:

  • If the element's setuid bit is set, only the element's owner, the VOB owner, or root can check out the version.
  • If the element's setgid 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 specify
  • –unreserved –nmaster or
  • –srfm

Options and arguments

Reserved and unreserved checkouts

Default
–res/erved unless a different default is specified in profile_ccase.
–res/erved
Reserves the branch: no user in another view can perform a reserved checkout of the same branch (but any number of unreserved checkouts can be performed); no new versions can be created on the branch until your checkout is changed to unreserved with unreserve or resolved with checkin or uncheckout. If you specify both –reserved and –unreserved, this command performs a reserved checkout if possible; otherwise, an unreserved checkout.
–unr/eserved [ –nma/ster ]
Leaves the branch unreserved; other users, in other views, can check out the same version (but at most one of the checkouts can be reserved).

With –nmaster, checks out the branch even if the current replica does not master the branch. Do not use this option if you cannot merge versions of the element.

For a discussion of how new versions are created from reserved and unreserved checkouts, see the checkin reference page.

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 path name as the element (dynamic view).
  • A modifiable copy of the version being checked out with the same path name as the element (snapshot view).

Exception: (Dynamic views) If the version being checked out is a derived object, it is winked in to the view.

–out dest-pname
(Does not apply to directories or DO versions) Creates a writable file under an alternate file name (perhaps in a different directory). No view-private file named pname is created. The cleartool ls command lists the element as checkedout but removed.
–nda/ta
(Does not apply to directories) Creates a checkout record for the version, but does not create an editable file that contains its data. The ls command lists the file as checked out but removed. This option is useful for checking out files that will be overwritten (for example, staged binaries or other files that are copied into place).

Preserving modification time

Default
checkout resets the file's modification time to the checkout time.
–pti/me
In a dynamic view, preserves the modification time of the file being checked out. This option is silently ignored when you use it in a snapshot view. Use this option consistently for checkout and checkin operations: if you specify –ptime when checking out a file, then specify –ptime when you check it in.

Nonstandard 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.

–bra/nch branch-pname
Specifies the branch whose most recent version is to be checked out. For example, to check out the latest version on branch ports, specify –branch \main\ports.
–ver/sion
Allows the checkout of a version that is not the latest on its branch.

Checkout with synchronous request for mastership (replicated VOBs)

Default
None.
–srfm
Issues a request for branch mastership synchronously with the checkout command.

Suppressing warning messages

Default
Warning messages are displayed.
–nwa/rn
Suppresses warning messages.

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.
–c/omment comment | –cfi/le comment-file-pname |–cq/uery | –cqe/ach | –nc/omment
Overrides the default with the option you specify. See the comments reference page.

Querying for the resolution of checkout problems

Default
Queries for the resolution of a checkout problem.
–q/uery
Queries for the resolution of a checkout problem.
–nq/uery
Does not query for the resolution of a checkout problem.
–use/hijack
Instructs checkout to use the hijacked file as the checked-out version. If the file being checked out does not have a hijacked counterpart, this option is silently ignored.

Element argument

Default
None.
pname ...
Path names of one or more elements to be checked out.

Examples

The UNIX system and Linux 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

See also

checkin, config_spec, ln, lscheckout, merge, mkbranch, mkdir, mkelem, mv, profile_ccase, protect, reqmaster, reserve, rmname, setactivity, uncheckout, unreserve

Feedback