Rational ClearCase Commands Referenceannotate
apropos
catcr
catcs
cc.icon
cc.magic
cd
chactivity
chbl
checkin
checkout
checkvob
chevent
chflevel
chfolder
chmaster
chpool
chproject
chstream
chtype
chview
clearaudit
clearbug
cleardescribe
cleardiffbl
cleardiff
clearexport_ccase
clearexport_cvs
clearexport_pvcs
clearexport_rcs
clearexport_sccs
clearexport_ssafe
clearfsimport
cleargetlog
clearhistory
clearimport
clearjoinproj
clearlicense
clearmake
clearmake.options
clearmrgman
clearprojexp
clearprompt
cleartool
clearviewupdate
clearvobadmin
comments
config_ccase
config_spec
cptype
credmap
creds
deliver
describe
diffbl
diffcr
diff
dospace
edcs
endview
env_ccase
events_ccase
export_mvfs
exports_ccase
file
find
findmerge
fmt_ccase
getcache
get
getlog
help
hostinfo
init_ccase
ln
lock
lsactivity
lsbl
lscheckout
lsclients
lscomp
lsdo
lsfolder
lshistory
ls
lslock
lsmaster
lspool
lsprivate
lsproject
lsregion
lsreplica
lssite
lsstgloc
lsstream
lstype
lsview
lsvob
lsvtree
makefile_aix
makefile_ccase
makefile_gnu
makefile_pmake
makefile_smake
makefile_sun
man
merge
mkactivity
mkattr
mkattype
mkbl
mkbranch
mkbrtype
mkcomp
mkdir
mkelem
mkeltype
mkfolder
mkhlink
mkhltype
mklabel
mklbtype
mkpool
mkproject
mkregion
mkstgloc
mkstream
mktag
mktrigger
mktrtype
mkview
mkvob
mount_ccase
mount
msdostext_mode
mvfslog
mvfsstorage
mvfstime
mvfsversion
mv
omake
pathnames_ccase
permissions
profile_ccase
promote_server
protect
protectvob
pwd
pwv
query_language
quit
rebase
recoverview
reformatview
reformatvob
register
relocate
rename
reqmaster
reserve
rgy_backup
rgy_check
rgy_passwd
rgy_switchover
rmactivity
rmattr
rmbl
rmbranch
rmcomp
rmdo
rmelem
rmfolder
rmhlink
rmlabel
rmmerge
rmname
rmpool
rmproject
rmregion
rmstgloc
rmstream
rmtag
rmtrigger
rmtype
rmver
rmview
rmvob
schedule
schemes
scrubber
setactivity
setcache
setcs
setplevel
setsite
setview
shell
snapshot.conf
softbench_ccase
space
startview
type_manager
umount
uncheckout
unlock
unregister
unreserve
update
version_selector
view_scrubber
vob_restore
vob_scrubber
vob_sidwalk
vob_snapshot
vob_snapshot_setup
wildcards_ccase
winkin
xclearcase
xcleardiff
xmldiffmrg
DESCRIPTION
During the import stage, you invoke clearimport within an existing VOB on the datafile created by clearexport_*. For each object processed by clearexport_* and entered in datafile, clearimport does one of the following things:
- Creates
a new element with the same versions as the original.
The user who invokes clearimport becomes the owner of the elements that clearimport creates. clearexport_* and clearimport use magic files to determine which element type to use for each element clearimport creates. For more information about magic files and file-typing, see the cc.magic reference page.
- Checks out an existing element (optionally, on a branch) and checks in a new version for each original version that has not already been imported.
If any of the original files were located in subdirectories, clearimport creates corresponding directory elements.
To select the directory version into which it imports elements, clearimport uses your view (UNIX) or your view context (Windows). However, when clearimport creates directory versions, it creates them on the main branch. The exceptions are as follows:
- If a directory already exists in the target VOB, you can check it out on a branch, and clearimport uses that version.
- If you are exporting with clearexport_ssafe and you use the –b option, clearimport imports to the specified branch.
When importing into a snapshot view, you can improve performance significantly by specifying –noload option.
Creation of Event Records During the Import Phase
clearimport documents changes to the VOB by creating event records:
- Each time clearimport creates a new file element, it stores an import file element event record, along with the standard create element event record, in the VOB database. The import file element event record is associated with the parent directory element, not with the new file element itself. clearimport creates the import event record only if the object is more than 24 hours old.
- Each time clearimport creates a new version, it annotates the standard create version event record with the comment from the original version.
- Each time clearimport creates a new VOB symbolic link, it creates a standard create symbolic link event record.
- clearimport always stamps the import file element event record with the current time. It stamps the create version and create element event records according to the original data unless you use the –nsetevent option.
- clearimport stamps
the event record for the creation of a branch with the same time stamp as
the version at which it was created.
Note: When clearimport creates a branch, the branch and version 0 of the element inherit the history information (user, group, and time stamp) of the version from which the branch sprouts.
- clearimport stamps the event record for attachment of an attribute, label, or merge arrow with the same time stamp as the associated version.
- clearimport stamps event records for the creation of directory elements and type objects with the current time and attaches the comment created by importer or the comment given with the –comment option.
- clearimport labels all directories and their imported parents with the union of all labels applied during import to versions contained in those directories. To defeat this behavior, use the -nolabeldir option.
Incremental Import and Restartability
clearimport can skip certain versions or entire elements, which gives you some flexibility:
- You can import an element in several passes. You may use incremental import to budget time efficiently (when there are too many versions to import at once) or because the original element is still being developed.
- You can restart clearimport if it terminates prematurely for any reason. clearimport quickly updates versions it has already imported, effectively resuming where it left off.
Caution: If you invoke clearimport with the –nsetevent option, it creates ClearCase or ClearCase LT versions that are newer than all the original files to be imported; thus, it is not restartable.
For each source version, clearimport does not create a corresponding version if it already exists on the target branch—that is, if it has the same time stamp (or a more recent one). However, even when clearimport bypasses version creation, it still updates the new version's metadata, such as version labels, using information from the source version.Preserving the Case of Files Imported to Windows Systems
By default, clearimport converts all file names to lowercase. This is generally the simplest and most efficient way to import files when you use the MVFS option of case-insensitive mode (the default). Converting file names on import mirrors the behavior of new files created in case-insensitive mode. For more information, see the Administrator's Guide.
Use the –pcase option when you need to preserve the case of files being imported; for example, when you import files whose names differ only in case (for example, Makefile and makefile), and you have disabled case-insensitive mode.
Handling of Unreadable or Troublesome Elements
clearimport prints an error when it cannot read an element version specified in the export data file. It creates version 0 of the unreadable element and continues to process the export datafile. Additionally, if clearimport has any difficulty importing any elements, it prints a list of such elements after it finishes.
RESTRICTIONS
Identities
You must be root (UNIX) or the VOB owner to run clearfsimport unless you invoke it with the -nsetevent option.
Locks
If it encounters a VOB lock while trying to write data during an import operation, clearimport pauses and retries the operation every 60 seconds until it succeeds.
Mastership
(Replicated VOBs only) Your current replica must master the branch types, branches, elements, and type objects involved in the import. With the -master option, the importer can create a new element and its main branch even if the main branch is not mastered by your current replica. The –master option also allows auto-make-branch during element creation; mastership of newly created branches is assigned to the current replica. When you specify the –master option, you must be able to check out the parent directory of the new element.
Other
The following restrictions apply:
- The source and target directories cannot be the same; to create elements from objects that already reside in the target directory, use mkelem.
- If you are importing ClearCase or ClearCase LT files, use the same config spec (the same view) for the export phase (invocation of clearexport_ccase) and the import phase (invocation of clearimport).
- Do not run clearimport in a view that has file elements checked out from the target VOB. If clearimport is importing to a checked-out element in the target VOB, it cancels the checkout (uncheckout) of that element and deletes the view-private file from the view storage directory. Any changes that you made to the file are lost.
- Do not run clearimport in a UCM view; use clearfsimport instead.
- When
you import PVCS, RCS, SourceSafe, or SCCS files, clearimport uses
an extraction command specific to the version-control product. You must have
this extraction command in your path during import:
PVCS and SCCS use the same command; make sure that the correct one is in your path.
- Do not run clearexport_* on UNIX and then run clearimport on Windows to import the data, or vice versa. However, you can transfer data in either direction between UNIX and Windows by mounting the UNIX VOB or file system on your Windows machine and running both clearexport_* and clearimport on the Windows machine.
OPTIONS AND ARGUMENTS
Verbosity of Output
- Default
- clearimport prints
a header for each kind of type creation (label, branch, attribute, and so
on). When it creates directory elements, file elements, and VOB symbolic links,
it prints a header as well as element names and version IDs. When the import
is completed, clearimport prints a message indicating that
it has closed the directories.
- –v·erbose
- clearimport prints
messages when it performs these operations: creates types, branches, directories,
VOB symbolic links, attributes, or version labels; draws merge arrows; makes
branches or elements obsolete; checks in or cancels checkouts of directories;
and checks out on a branch.
Creation of Identical Successor Versions
- Default
- When you invoke clearimport on
a datafile created by clearexport_*,
it does not create a new version that is identical to its predecessor.
- –i·dentical
- Creates a new version even if it is
identical to its predecessor, but only if the file has a more recent date
than the date on the version in the VOB.
Transcription of History Information
- Default
- The exporters extract historical information
from each object and place it in the object's description in the datafile.
The create version and create
element event records created for the object by clearimport have
the same information—user, group, and time stamp—as the original
object.
Note: When clearimport creates a branch, the branch and version 0 of the element inherit the history information of the version from which the branch sprouts.
- –n·setevent
- Event records and historical information
for new elements and versions reflect who ran the execution of clearimport and
when, not the original data. You cannot use this option when you import a
datafile created with clearexport_ccase.
Caution: If you invoke clearimport with the –nsetevent option, it is not restartable.
Mastership of the Main Branch
Preserve Case of Files
Specifying a Destination Directory
Event Records and Comments
Suppressing Snapshot View Loads
- Default
- Imported elements are loaded into the
snapshot view.
- –no·load
- Suppresses the loading of imported elements
into snapshot views. The view's config_spec must
include a load rule that specifies the destination of the imported elements
and a version-selection rule that specifies /main/LATEST.
To see the new elements, you must update the view after the import operation
(see update).
Specifying this option can improve clearimport performance substantially. If you also specify the –identical option, clearimport does not compare element versions to determine whether they are identical. Used with –noload, -identical can further improve clearimport performance.
Specifying the Data File
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.
Note: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf—for example, /vobs/src. A single-component VOB tag consists of a leaf only—for example, /src. In all other respects, the examples are valid for ClearCase LT.