clearimport
Reads data files created
by clearexport tools and import elements into a VOB
SYNOPSIS
- UNIX
only:
- clearimport [ –v·erbose]
[ –i·dentical] [ –n·setevent ]
[ –master ]
- [ –d·irectory destination-dir]
[ –c·omment comment]
[ –no·load ]
[ –nolab·eldir ] datafile
- Windows
only:
- clearimport [ –v·erbose]
[ –i·dentical] [ –n·setevent ]
[ –master ]
- [ –pcase ] [ –d·irectory destination-dir] [ –c·omment comment]
[ –no·load ] [ –nolab·eldir ] datafile
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:
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
- Default
- Assigns mastership of the element's main branch
to the VOB replica that masters the main branch.
- –master
- Assigns mastership of the main branch
of the element to the VOB replica in which you execute the clearimport command.
Preserve Case of Files
- Default
- clearimport converts
all file names to lowercase.
- –pcase
- Preserves the case of files being imported.
Specifying a Destination Directory
- Default
- clearimport imports
elements into the current directory.
- –d·irectory destination-dir
- clearimport imports
elements into the specified VOB directory.
Event Records and Comments
- Default
- clearimport attaches
the comment created by importer to any directories
created during the import process.
- –c·omment comment
- clearimport attaches
the specified comment instead of the default comment.
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
- Default
- None. You must specify the datafile on
which you want to invoke clearimport.
- datafile
- File created by clearexport_* command
(by default, named cvt_data).
Suppressing Directory Labeling
- Default
- Directories and their imported parents
are labeled with the union of all labels applied during import to versions
contained in those directories.
- –nolab·eldir
- Suppresses the labeling of imported
directory elements.
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.
- Invoke clearimport on cvt_data, forcing creation of identical versions and attaching a comment to new directories.
- Invoke clearimport on cvt_data, enabling verbose output and importing elements into the \newvob directory.
SEE ALSO
cc.magic, chtype, clearexport_ccase, clearexport_cvs, clearfsimport, clearexport_pvcs, clearexport_rcs, clearexport_sccs, clearexport_ssafe, events_ccase, protect, rename, setview, update