clearfsimport

Converts file system objects to element versions

Applicability

Product

Command type

VersionVault

command

Platform

UNIX

Linux

Windows

Synopsis

  • UNIX and Linux only; import file system objects in one pass:
    clearfsimport [ –preview ] [ –follow ] [ –recurse ] [ –rmname ]
    [–comment comment ] [ –mklabel label [ –upd/ates_only ] ] [ –nsetevent ] [ –identical ]

    [ –master ] [ –unco ] source-name [ . . . ] target-VOB-directory

  • UNIX and Linux only; import file system objects in two passes:
    clearfsimport [ –follow ] [ –recurse [ –filter ] ] [ –rmname ]
    [–comment comment ] [ –mklabel label [ –upd/ates_only ] ] [ –nsetevent ] [ –identical ]

    [ –master ] [ –unco ] source-name [ . . . ] target-VOB-directory

  • Windows only; import file system objects in one pass:
    clearfsimport [ –preview ] [ –recurse ] [ –rmname ]
    [ –comment comment ] [ –mklabel label [ –upd/ates_only ] ] [ –nsetevent ]

    [ –identical ] [ –master ] [ –unco ]

    [ –downcase ] source-name [ . . . ] target-VOB-directory

  • Windows only; import file system objects in two passes:
    clearfsimport [ –recurse [ –filter ] ] [ –rmname ]
    [ –comment comment ] [ –mklabel label [ –upd/ates_only ] ] [ –nsetevent ]

    [ –identical ] [ –master ] [ –unco ]

    [ –downcase ] source-name [ . . . ] target-VOB-directory

Description

The clearfsimport command reads the specified file system source objects and places them in the target VOB. This command uses magic files to determine which element type to use for each element created (see the cc.magic reference page). The source and target directories may not be the same; to create an element from a view-private object that already resides in the target directory, use mkelem.

In addition to previewing an import operation, you can use this command to import file system objects in a single pass, or to import them in two passes.
  • Importing file system objects in a single pass is useful for populating a new VOB.
  • When you import in two passes, the first pass determines which elements that need to be checked out for the import to succeed. The second pass checks out only those elements and proceeds with the import operation. This mode is especially useful for updating replicated VOBs, when importing in a single pass would cause the oplogs to grow too large due to unnecessary checkout and uncheckout operations.

Restrictions

Identities

You must be root (UNIX and Linux) 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, clearfsimport 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.

Working directory

Because Windows prohibits renaming a directory that is in use, you cannot run clearfsimport in a snapshot view on Windows if the current working directory is also the target-VOB-directory.

Options and arguments

Previewing the results

Default
No preview.
–preview
Previews the import, listing all elements that the import would add or change, as well as any checkouts that would conflict with imports, but does not import anything. Because this option does not check permissions, the actual import may fail due to insufficient permissions.

Handling of UNIX or Linux symbolic links

Default
Processes each UNIX or Linux symbolic link as a VOB symbolic link with the same link text.
–follow
Processes the object to which a UNIX or Linux symbolic link points, instead of importing the link itself into the VOB.

Handling of directory arguments

Default
If a source-name argument names a directory to be imported, an element version is created for the directory and for each file, directory, UNIX symbolic link, or Linux symbolic link residing at the top level of the directory.
–recurse
Descends recursively into all source-name arguments that are directories.

Filtering unnecessary checkouts

Default
All elements are checked out.
–filter
Determines which elements need to be checked out for the import to succeed and checks out only those elements. When this option is specified with –mklabel , the label is applied to newly created directory versions only.

Handling of existing VOB directories

 Default
Existing VOB directories that are not present in the sources to be imported are left as is.
–rmname
For all source-name arguments that are directories, performs an rmname operation on elements that are already in the VOB but are not present in the source directory. If used in combination with -recurse, performs this rmname operation in all directories traversed. If used in combination with -downcase, performs the downcase operation before looking for matching names in the VOB.

Comments

Default
created by clearfsimport
–comment comment
Attaches the specified comment instead of the default comment to each element version checked in to the VOB.

Labeling

Default
No labeling.
–mklabel label
Attaches the specified label instance to each element that matches the name of an imported file or directory, whether or not a new version is created. If the label type does not exist, it is created. If the label is already attached to an existing element version, it is moved.
–upd/ates_only
Attaches the specified label instance only when a new element is created or an existing element is updated. The label is not applied unless the import actually creates a new version.

Event records

Default
Historical information associated with the sources is preserved.
–nsetevent
Specifies that event records and historical information for new elements and element versions show the user who executed clearfsimport and the date of execution, not the original data associated with the sources. This option creates element versions that are newer than the original sources; thus, the clearfsimport operation is not restartable after you have invoked it with this option.

Creation of identical successor versions

Default
Element versions that are identical to their predecessors in the source are not created.
–identical
Creates a new version of an element, even if it is identical to its predecessor, if the source has a more recent date than that of the version in the VOB.

Branch mastership

Default
The main branch of the element is mastered by the replica that masters the branch's type.
–master
Assigns mastership of the main branch of the element to the VOB replica in which you execute the clearfsimport command. If your config spec includes –mkbranch lines or mkbranch rules that apply to the element, clearfsimport creates these branches and assigns their mastership to the current VOB replica.

Handling of existing checked-out elements

Default
When clearfsimport encounters a checked-out element that exists in the target VOB and corresponds to a source to be imported, it prints an error and continues.
–unco
If a checked-out file element that corresponds to a source file to be imported exists in the target VOB, an uncheckout operation is executed on the element and the corresponding view-private file is retained with a suffix of .keep. The import operation then checks out the element again and checks in the imported version.

Handling of case of imported elements

Default
Case preserving.
–downcase
Changes names of imported elements to lowercase.
Note: When importing files from a UNIX or Linux host into a VOB on a Windows host, clearfsimport may be unable to operate correctly on files and directories that have mixed-case names. For example, if a mixed-case name is specified on the command line, clearfsimport creates the element name as specified, even when the form of the source name is different. Consistent use of -downcase can help avoid these problems. If you specify-downcase for an initial import from UNIX or Linux to Windows, specify it on any subsequent imports into the same VOB directories.

Specifying the source

Default
None.
source-name [. . .]
Flat files, directories, and UNIX or Linux symbolic links to be imported to the VOB. You can specify path names or use wildcards as described in wildcards_ccase.

For each path name, the leaf of the path name is imported into the target VOB. For example, /usr/src/lib/foo.c is imported into the VOB /vobs/mylib as /vobs/mylib/foo.c or into the VOB /bigvob as /bigvob/foo.c.

For each file, an element version is imported. If a corresponding version of the file exists in the target VOB and is checked out, clearfsimport prints and error and continues unless the -unco option was specified. A summary of import failures due to checked-out elements is printed at the completion of the import operation.

For each directory, versions are created for all files and UNIX or Linux symbolic links it contains. Also created is a directory element with one version for the directory and each of its subdirectories. Checked-out VOB directories that correspond to source directories to be imported are reused.

Note: source-name cannot be UNC path names.

Specifying the target VOB

Default
None.
target-VOB-directory
The VOB directory to which the sources are to be imported. This directory may not be the same as the directory from which the sources are being imported.

Examples

  • Preview a VOB—/vobs/projectx/src—that is to be populated with the contents of /usr/src/projectx. Recursively descend all directories encountered and follow UNIX or Linux symbolic links to the target objects.

    clearfsimport –preview –follow –recurse /usr/src/projectx
    /vobs/projectx/src

  • Convert a .txt file to an element and place it in the VOB lli_vob1.

    D:\lli_work>clearfsimport  Reqpro_setup.txt M:\lli_nt_view\lli_vob1
    Validating directory "M:\lli_nt_view\lli_vob1".
    Creating element "M:\lli_nt_view\lli_vob1\Reqpro_setup.txt".
    version "\main\1".
    Closing directories.
    Checked in version "main\1" of directory "M:\lli_nt_view\lli_vob1"