checkin
Creates a permanent new version
of an element
SYNOPSIS
- checkin | ci [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
- | –cqe·ach | –nc·omment ]
[ –nwa·rn ]
[ –cr ] [ –pti·me ]
[ –kee·p | –rm ]
[ –fro·m source-pname ]
[ –ide·ntical ] { –cact | activity-selector ...
| pname ... }
DESCRIPTION
To create a new version of an element, checkin makes
changes in the VOB and in the view.
Actions Taken in the VOB
For one or more elements, checkin creates
a successor to a version that was previously checked out in the current view:
the predecessor version. The version number of the successor is the next unused
number on the branch. (If one or more versions have been deleted from the
end of the branch with rmver, it may seem
that some version numbers have been skipped.) An appropriate message is displayed:
A checkin event record is created, which
can be listed with the lshistory command:
Only elements can be checked in. You cannot
check in a view-private or local file; you must first make an element of the
same name. Use the mkelem –ci command
to simultaneously create an element and check in a view-private or local file
as its first version.
Actions
Taken in the View
checkin works differently
in different contexts.
- Dynamic view. By default, the new version of a file
element is created by copying the contents of the view-private file named pname (the
checked-out version) to the VOB, and then deleting that file. The –keep and –from options
alter this behavior.
- Snapshot view. By default, the new version of a file
element is created by copying the contents of the file named pname (the
checked-out version) to the VOB. The checked-in version remains in the view.
(This version may not be the one specified by the config spec.) The –keep and –from options
alter this behavior. If multiple instances of this file element are loaded
into the view (because the load rules specify a hard-linked UNIX file or a
linked Windows file in more than one location), checkin updates
each instance of the file with the checked-in version.
After the element is checked in, your view
typically selects the version you just created. However, in a dynamic view
it is possible that your view selects another version (perhaps on another
branch), because that version is specified by your config spec rules. In this
case, checkin displays a warning message.
Metadata and the Checked-In Version
From the viewpoint of the VOB database,
the new, checked-in version is the same object as the checked-out version.
Thus, any metadata items (version labels, attributes, hyperlinks) that were
attached to the checked-out version remain attached to the new version. And,
for example, checkin followed by mklabel is
equivalent to mklabel followed by checkin.
Checkin of Reserved and Unreserved Checkouts
At the time you enter a checkin command,
there may be several checkouts of the same version. At most one of the checkouts
(perhaps yours) is reserved; all the others are unreserved. Your checkin command
succeeds in either of these cases:
- Yours
was a reserved checkout.
- All
checkouts were unreserved, and no one has checked in a successor version.
If the command fails because someone else
has a reserved checkout, you must wait until that checkout is resolved, with checkin, uncheckout, or unreserve.
If the command fails because someone has checked in a successor version before
you did, you can check in your work by performing the following steps:
- Merge
from the current LATEST version on the branch to
your checked-out version.
- Enter
the checkin command again.
Checkin of Derived Objects
(Dynamic views) You can check in a derived
object to make it a version of an element (a DO version). By default, both
the data and configuration record of a derived object are checked in. To save
disk storage, you can use the –cr option to check in
only the configuration record, not the data. Checking in a nonshareable DO
converts the DO, its sibling DOs, and its sub-DOs to shareable DOs.
clearmake can
reuse or winkin a derived object only if it is stored under its original pathname.
Thus, a DO version created under an alternate name with checkin –from cannot
be used by clearmake for build avoidance.
(clearmake can still use the derived object
named in the –from option, which is unaffected by this
command.)
For information about creating a file element
for a DO, see the mkelem reference page;
for information about subsequent operations on DO versions, see Building Software.
RESTRICTIONS
Identities
You must have one
of the following identities:
- User
who checked out the element
- Element
owner
- VOB
owner
- root (UNIX)
- Member
of the ClearCase administrators group (ClearCase on Windows)
- Local
administrator of the ClearCase LT server host (ClearCase LT on Windows)
Additional restrictions on UNIX:
- If
the element's setuid bit is set, only the element's
owner, the VOB owner, or root can check in 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
in the version.
Locks
An error occurs if one or more of these objects
are locked: VOB, element type, branch type, element, branch, pool (file elements).
Mastership
(Replicated VOBs)
Your current replica must master the branch on which you are checking in the
version.
OPTIONS AND ARGUMENTS
Event Records and Comments
- Default
- Creates one or more event records, with
commenting controlled by your home directory's .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.
Note: If a checkout comment exists (specified with the checkout command
and/or generated to record changes to a checked-out directory), you can make
it the checkin comment by using one of the following commands:
Suppressing Warning Messages
- Default
- Warning messages are displayed.
- –nwa·rn
- Suppresses warning messages.
Checking In Derived Objects
- Default
- checkin checks in both
the data and configuration record for a derived object.
- –cr (For derived object checkin)
- Checks in only the configuration record
for the specified derived objects. Each new DO version will have a configuration
record, but no data. You can use many cleartool commands
with such DO versions, such as catcr, diffcr, and mklabel (but
not lsdo). DO versions are also visible
when you use the ls command. However, a
version created with this option cannot be opened or executed, because there
is no data.
Managing Source Files
- Default
- In
a dynamic view, checkin deletes each view-private, checked-out pname file
after using it to create a new version.
- In
a snapshot view, checkin uses the checked-out pname file
to create a new version, then loads the checked-in version into the view.
You can use the following options (which
have no meaning for directory elements) to save view-private copies or to
check in source files from other locations.
- –kee·p
- Saves the current contents of each checked-out
version in a view-private file, in addition to creating a new version. The
view-private file gets a name of the form pname.keep (or
possibly, pname.keep.n). –keep is
the default when you use the –from option, because
the current contents of the checked-out version would otherwise be lost.
- –rm
- Removes each pname file
after creating a new version. In a dynamic view, this is the default if you
do not use the –from option.
- –fro·m source-pname
- Uses the contents of source-pname as
the new version, instead of the view-private file pname.
By default, –keep is invoked to preserve the contents
of the view-private pname. The source-pname file
itself is not affected. This option makes it easy to copy data from another
location (outside the VOB, perhaps) into an element's version tree.
When using this option, specify only one pname argument.
- In a snapshot view, you cannot use a view-extended pathname
as source-pname.
- This option will not work
on directories.
Miscellaneous Options
- Default
- checkin resets the new
version's modification time to the checkin time. Also, checkin cancels
the checkin operation for files managed by certain type managers, if the contents
of the files match their predecessor versions.
- –pti·me
- Preserves the modification time of the file
being checked in. If you omit this option, cleartool sets
the modification time of the new version to the checkin time.
Note: On some UNIX platforms, it is important
that the modification time be preserved for archive files (libraries) created
by ar(1) (and perhaps updated with ranlib(1)).
The link editor, ld(1), complains if the modification time
does not match a time recorded in the archive itself. Be sure to use this
option, or (more reliably) store archive files as elements of a user-defined
type, created with the mkeltype –ptime command. This
causes –ptime to be invoked when the element is checked
in.
- –ide·ntical
- Checks in the element even if the predecessor
version is identical to the checked-out version. By default, the checkin operation
is canceled in such cases.
Note: This behavior applies only to elements
whose type manager computes version-to-version deltas (for example, elements
of type text_file, binary_delta_file,
and compressed_text_file). If an element's type manager
does not compute deltas, checkin always creates a new version,
even when it is identical to its predecessor. For example, a new version is
always created for an element of type file, which
uses the whole_copy type manager.
Specifying Objects to Check In
- Default
- None.
- –cact
- Checks in each checked-out version in the
change set of the current UCM activity in your view.
- activity-selector ...
- Checks in each checked-out version in the
change set of each specified activity. Specify activity-selector in
the form activity:activity-name[@vob-selector]
- pname ...
- The pathnames of one or more elements to
be checked in.
EXAMPLES
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.
- After
verifying its checkout comment, check in element util.c,
using that comment.
- Check
in an element from another file, discarding the checked-out version. Provide
a comment on the command line.
- (ClearCase)
Check in only the configuration record of a derived object, discarding its
data.
SEE ALSO
catcr,
checkout,
clearmake,
config_spec,
diffcr,
get, ls, lsdo, lshistory, merge, mkelem,
mkeltype,
mklabel,
profile_ccase,
rmver, uncheckout,
unreserve