NAME ctupdate - integrate missing or newer files into a ClearCase VOB VERSION 1.17-r350 SYNOPSIS ctupdate [(--verbose | --tell-actions)] [--protocol=] [(--args-env=)...] [--args-from=] (--comment= | --comment-from= | --no-comment) ( [(--label= | --replace-label=)] [--no-dest-root-label] [--make=] [--update=] [--erase=] ( [(--flat | --recursive) [--source-root=]] [--reset-exceptions] ( [--exclude-file=] [--exclude=] [--include-file=] [--include=] )... (--source=)... )... --dest-root= )... ctupdate --help [...] ctupdate --version DESCRIPTION The command checks all source file system elements specified by the arguments of option --source, whose corresponding elements in the tree spanned by the current destination root specified by the argument of option --dest-root are missing or are out of date. For each such source file system element the program determines, if it has to be handled by matching its current source root relative path against each element contained in the exception list of the current destination root till a match succeeds. The first successful match stops the matching process and if the matching element was marked for exclusion, the file system element is not handled, else if the element was marked for inclusion or if none of the exception list elements matches, the file system element is handled. Each file system element determined to be handled is copied to the destination tree according to the options --make and --update. Option --erase controls if destination file system elements in directories corresponding to a source directory not existing there are erased. Unless option --flat is in effect, for source file system elements designating a directory the whole tree spanned by this directory is handled. The option arguments may contain pattern matching operators as explained in section FILENAME EXPANSION. Be sure to quote them according to the needs of the shell used. For ctupdate to work, the argument of option --dest-root has to designate a ClearCase VOB element, and exactly one of the comment options --comment, --comment-from or --no-comment has to be given. For convenience, the option specifiers --source= and --dest-root= of trailing options may be omitted. Unless option --help or --version is supplied, the command returns with an exit code 0 on success and with an exit code 1, if any error did occur. GLOBAL OPTIONS --help -h If no argument follows, print the command man page on standard output, else the description of the options and exit with exit code 2. The arguments shall be stated without leading '-' or '--'. --version -V Print version info on standard output and exit with exit code 2. --verbose -v Issue additional diagnostic messages on stdout. This option acts globally and is mutually exclusive with the option '--tell-actions'. --tell-actions -t Perform no actions, issue messages on stdout instead. This option acts globally and is mutually exclusive with the option '--verbose'. --protocol= -P Generate the application protocol in . By default, the protocol file 'ctupdate.txt' is generated in the current directory, unless the current directory is not writable or the generation of a protocol is switched off by '--protocol=-'. This option acts globally. --args-env= -E Defines an argument environment variable. The option argument shall be of the form =. The argument environment variable with value can be used in option or command arguments of the command line with the construct '@{}' which is replaced then by . If an argument environment variable is not found, next a shell environment variable is searched. If also this variable does not exist, the construct is not replaced. --args-from= -A Substitutes the content of into the command line. The file shall contain valid command line options and command arguments with the extension that newline or '#' or ';' characters followed by arbitrary content up to the line end are regarded as white space. Especially may contain other options '--args-from', or argument or shell environment variable definitions and usages. --comment= -c Use as ClearCase check in comment. This option acts globally. --comment-from= -C Use the content of as ClearCase check in comment. The file shall not be inside the tree spanned by . This option acts globally. --no-comment -n Use no ClearCase check in comment. This option acts globally. --dest-root= -D End the scope of the current destination root, define its path by and begin a new destination root scope with still undefined path. The destination root of the just ended destination root scope corresponds to all source roots in the source tree defined within this scope. DESTINATION ROOT LOCAL OPTIONS --source-root= -S Set as current source root. This current source root always corresponds to the current destination root in the destination tree. This means that all arguments following this option are regarded relative to in the source tree and relative to the current destination root in the destination tree. The source root defined by is valid till another option --source-root occurs or till the scope of the current destination root is ended by option --dest-root. The default value of the current source root is the current directory and since this is a redefinable destination root local option, this means that for each destination root this default can be redefined by a new --source-root option. --label= -l Label all current destination root file system elements handled which are plain files or directories just checked in or containing at least one element which also has been labeled with the labels specified by the non-empty whitespace or comma separated list . The ClearCase label names are generated from each list element by brace expansion as in the bash shell. Be sure to quote according to the needs of the shell used. If a label name does not yet exist, it is created. This option may be used only in conjunction with '--mode=checked-in' and '--update=checked-in'. It is an error, if some other ClearCase version of an element to be labeled already bears the label. This is a destination root local option, meaning that for each destination root a new set of labels has to be defined. --replace-label= -L Label all current destination root file system elements handled which are plain files or directories just checked in or containing at least one element which also has been labeled with the labels specified by the non-empty whitespace or comma separated list . The ClearCase label names are generated from each list element by brace expansion as in the bash shell. Be sure to quote according to the needs of the shell used. If a label name does not yet exist, it is created. This option may be used only in conjunction with '--mode=checked-in' and '--update=checked-in'. If some other Clearcase version of an element to be labeled already bears the label, this existing label is moved to the version just handled. This is a destination root local option, meaning that for each destination root a new set of labels has to be defined. --no-dest-root-label -N Do not label the current destination root directory. By default the current destination root directory is labeled as other destination directories. This is a destination root local option, meaning that for each destination root this option is not in effect by default. --make= -m Make mode: is one of the following modes for making a new destination element: 'vp' or 'view-private': make a view private element (default), 'ci' or 'checked-in': make a checked in VOB element, 'co' or 'checked-out': make a checked out VOB element. If the defaults '--make=view-private', '--update=reversible' and '--erase=no' have been used, the actions done by ctupdate may be revoked by 'ctoperate --operation=remove'. This is a destination root local option, meaning that for each destination root, initially the default make mode 'view-private' is in effect, and a new make mode may be defined. --update= -u Update mode: is one of the following modes for updating an existing destination element: 'rv' or 'reversible': update the element reversibly (default), 'ci' or 'checked-in': update the element and check it in, 'co' or 'checked-out': update it leaving it checked out. If the defaults '--make=view-private', '--update=reversible' and '--erase=no' have been used, the actions done by ctupdate may be revoked by 'ctoperate --operation=remove'. This is a destination root local option, meaning that for each destination root, initially the default update mode 'reversible' is in effect, and a new update mode may be defined. --erase= -e Erase mode: is one of the following modes for erasing a destination element which does not correspond to a source element: 'no': do not erase the element (default), 'vp' or 'view-private': erase it only if it is view private, 'all': erase it under all circumstances. If the defaults '--make=view-private', '--update=reversible' and '--erase=no' have been used, the actions done by ctupdate may be revoked by 'ctoperate --operation=remove'. This is a destination root local option, meaning that for each destination root, initially the default erase mode 'no' is in effect, and a new erase mode may be defined. --flat -f Suppress recursive descent into the trees spanned by source directories. This is a redefinable destination root local option, meaning that for each destination root, it has to be set anew and, moreover can be reset for each new source root by option --recursive. --recursive -r Request recursive descent into the trees spanned by source directories. This option is in effect by default and since it is a redefinable destination root local option, this means that for each destination root, it is initially in effect, but can be reset for each new source root by option --flat. --exclude-file= -x Add all source file system elements matched by to the exception list of the current destination root and mark them for exclusion. This option may be supplied more than once and may contain pattern matching operators as explained in section FILENAME EXPANSION. Be sure to quote according to the needs of the shell used. If ends with a path separator character, the matching process is restricted to directories else to plain files. The matching occurs recursively for all defined source file system elements of the current source root. If begins with a path separator the matching is anchored at this source root. This is a destination root local option, meaning that for each destination root the exception list is initially empty. --exclude= -X Add all source file system elements matched by to the exception list of the current destination root and mark them for exclusion. This option may be supplied more than once and may contain pattern matching operators as explained in section FILENAME EXPANSION. Be sure to quote according to the needs of the shell used. If ends with a path separator character, the matching process is restricted to directories. The matching occurs recursively for all defined source file system elements of the current source root. If begins with a path separator the matching is anchored at this source root. This is a destination root local option, meaning that for each destination root the exception list is initially empty. --include-file= -i Add all source file system elements matched by to the exception list of the current destination root and mark them for inclusion. This option may be supplied more than once and may contain pattern matching operators as explained in section FILENAME EXPANSION. Be sure to quote according to the needs of the shell used. If ends with a path separator character, the matching process is restricted to directories else to plain files. The matching occurs recursively for all defined source file system elements of the current source root. If begins with a path separator the matching is anchored at this source root. This is a destination root local option, meaning that for each destination root the exception list is initially empty. --include= -I Add all source file system elements matched by to the exception list of the current destination root and mark them for inclusion. This option may be supplied more than once and may contain pattern matching operators as explained in section FILENAME EXPANSION. Be sure to quote according to the needs of the shell used. If ends with a path separator character, the matching process is restricted to directories. The matching occurs recursively for all defined source file system elements of the current source root. If begins with a path separator the matching is anchored at this source root. This is a destination root local option, meaning that for each destination root the exception list is initially empty. --reset-exceptions -d Delete the exception list of the current destination root. SOURCE ROOT LOCAL OPTIONS --source= -s Add all file system elements in the tree spanned by the current source root matched by to the list of source file system elements to be handled for this source root. This option may be supplied more than once and may contain pattern matching operators as explained in section FILENAME EXPANSION with the exception that operator '**' is not supported. Be sure to quote according to the needs of the shell used. If ends with a path separator character, the matching process is restricted to directories. As the matching always occurs relative to the current source root, shall be relative and designate file system elements inside the tree spanned by the current source root. This is a source root local option, meaning that for each source root the list of file system elements to be handled is initially empty. FILENAME EXPANSION The evaluation of the arguments is done using pattern matching based file name expansion. If contains one of the unescaped extended regular expression operators '(' or '|', it is interpreted as extended regular expression as defined in the Open System Group Base Specification Issue 6, IEEE Std 1003.1-2004 (XBD: 9.4). Otherwise if contains no unescaped '{', it is interpreted as filename expansion pattern. Else is brace expanded as in the bash shell and each of the resulting words is interpreted as filename expansion pattern. Filename expansion patterns are defined as in IEEE Std 1003.1-2004 (XCU: 2.13.3). As mandated by IEEE std 1003.1-2004 these pattern matching based file name expansion operations occur for each path separator separated part of independently. To circumvent this, the operator '**' as last characters of such a part matches a sequence of zero or more pairs each consisting of a file system element name component and a path separator. The bracket expressions used in the regular expressions and in the filename expansion patterns conform to IEEE Std 1003.1-2004 (XBD: 9.3.5) with the exception that equivalence classes [=x=] of collating elements are not supported. On windows systems the escape character for extended regular expressions, filename expansion patterns and brace expansion is '%' instead of the usual '\' and as path separators both '/' and '\' are allowed. On other systems only '/' is allowed as path separator and both '\' and '%' may be used as escape characters. So for portability reasons it is recommended on all systems to use '/' as path separator and '%' as escape character. EXAMPLE Let the environment variable 'STMDEVLROOT' be set to the value 'D:\Development\SysToMath\wcopies', 'PACKAGE' to the value 'LibStmC', and 'CLEARCASEVOB' to the value 'Z:\wbit_cr'. Moreover, let the ctupdate argument file 'ctupdate.arg' in the package directory have the following content: --args-env=StmPackage=@{PACKAGE} --args-env=StmPkgRoot=@{STMDEVLROOT}/@{StmPackage} # Package directory --protocol=@{StmPkgRoot}/ctupdate.txt --make=checked-in --update=checked-in --erase=all --comment-from=@{StmPkgRoot}/release.txt --no-dest-root-label --source-root=@{STMDEVLROOT} --exclude=.svn/ --exclude="(DebugMt|DebugMtDll|DebugMtStaticRt)/" --exclude="(ReleaseMt|ReleaseMtDll|ReleaseMtStaticRt)/" --exclude-file="*.{suo,ncb,aps,user,log,bak}" --exclude-file="/@{StmPackage}/etc/revision*" --exclude-file=/@{StmPackage}/release.txt --exclude-file=/@{StmPackage}/ctupdate.txt --source=@{StmPackage} --dest-root=@{CLEARCASEVOB}/tools/utilities/packets Then with the package directory as the current working directory, the command 'ctupdate --label=LibStmC-1.7.328 --args-from=ctupdate.args' will update and label the package 'LibStmC' in the ClearCase VOB. The according protocol will be written to the file 'ctupdate.txt'. AUTHOR (C) 2005-2008 Tom Michaelis, SysToMath