NAME

synctree - Normalize a tree of flat files with a tree of ClearCase elements

SYNOPSIS

  synctree -sbase /tmp/newcode -dbase /vobs_tps/xxx

Take all files located under /tmp/newcode, remove the leading "/tmp/newcode" from each of their pathnames, and place the remaining relative paths under "/vobs_tps/xxx" as versioned elements, leaving them checked out.

  synctree -cr -yes -ci -sbase /vobs/hpux/bin -dbase /vobs_rel/hpux/bin

Sync all files under "/vobs_rel/hpux/bin" with those in "/vobs/hpux/bin", making sure to preserve their CR's. Suppress interactive prompting and check in all work when done.

  synctree -sb /A/B -db /X/Y -map /A/B/foo /X/Y/bar /A/B/here /X/Y/there

Take 'foo' from directory /A/B and check it in as 'bar' in /X/Y. Similarly, create an element /X/Y/there with the contents of /A/B/here.

DESCRIPTION

Synctree brings a VOB area into alignment with a specified set of files from a source area. It's analogous in various ways to clearfsimport, citree, and clearexport/clearimport; see the COMPARISONS section below. Synctree is useful if you have a ClearCase tree that must be kept in sync with a CVS tree during a transition period, or for overlaying releases of third-party products upon previous ones, or exporting deliverable DO's from a nightly build to a release VOB while preserving config records (CR's) and labels, or similar.

The default operation is to mkelem all files which exist in <src> but not in <dest>, modify any files which exist in both but differ, but not to remove files which are present in <dest> and not in <src>. Adding the -rmname flag will cause this removal to happen as well and thus make the <src> and <dest> areas identical.

Synctree need not run in a view context itself but the directory named by the -dbase flag must provide a view context. The branching behavior of any checkouts performed will be governed by that view's config spec. The -dbase directory need not exist, as long as it lies under a mounted VOB tag and in a view context. In other words, synctree can auto-create the destination directory tree.

The list of source files to operate on may be provided with the -flist option or it may come from @ARGV. Any directories encountered on the command line will be traversed recursively. If no source-file-list is provided, the directory specified with -sbase is used as the default.

File paths may be given as relative or absolute. Destination paths are determined as follows: all source filenames are first turned into absolute paths if necessary, then the source preface given with the -sbase parameter is removed and replaced with the value of -dbase to produce the destination pathname (but see FILE MAPPING below).

ClearCase symbolic links are supported, even on Windows. Note that, unless you use the -rellinks flag, the text of the link is transported verbatim from source area to dest area; thus relative symlinks may no longer resolve in the destination area.

Consider using the -n flag the first time you use this on a valued VOB, even though nothing irreversible (rmelem, rmbranch, rmver, rmtype, etc.) is ever done by synctree. And by the same token use -yes and -ci with care.

OPTIONS

Not all options are described here, only those requiring elaboration beyond the -help summary. Run synctree -help for a full option summary.

• -force, -stop

  By default, upon encountering a ClearCase error synctree will attempt to return to the initial state by undoing all checkouts etc. The -stop flag will cause it to exit immediately leaving the partial state intact while -force will cause it to blunder onward, ignoring errors. However, even with -force a nonzero status is returned if errors are encountered.

• -ignore_co, -overwrite_co

  By default, synctree refuses to run if any view-private files exist under the destination base. This includes checkouts, which are a special form of view private file. The -ignore_co flag allows synctree to continue in this situation. As the flag name implies it will ignore these checkouts; i.e. differences in the source base will not overwrite the checked-out file in the destination. The -overwrite_co flag also allows synctree to proceed in the presence of existing checkouts but causes them to be overwritten by the source version.

• -no, -yes, -ci

  The -no flag causes synctree to report what it would do and exit without making any changes, -yes suppresses all prompts except for the check in changes? prompt, and -ci suppresses that one. The default behavior is to prompt before making changes. To suppress all prompting you must use both -yes and -ci.

• -label, -lbmods

  The -label option let you specify a label to be applied before finishing. By default it will label recursively from the -dbase area down, as well as all parent directories upward to the vob root. But if the -lbmods flag is used as well, only modified elements will be labeled.

• -reuse

  If element X is created in synctree run #1, rmname'd in run #2, and created again in run #3, you may end up with multiple elements with the same name. This situation is known as an evil twin. The -reuse flag can avoid this; before making a new element it searches the directory's version tree looking for a prior element of the same name. If found, it will link the old element back into the current version of the directory, then (if the contents differ) check it out and replace the contents with those of the source file.

  This flag can avoid evil twins and save storage space but will run a little slower due to the extra analysis. Also, there's no guarantee the prior element of the same name is in fact logically related to the new one. They could conceivably even be of different element types.

  The -reuse feature is not well tested and should still be considered experimental.

• -vreuse

  If two alternative releases of the same tree are imported in alternation, new versions are created at every step, as the result of even imports is systematically hidden by odd ones.

  This flag will check for suitable versions of the elements in their version tree, and apply there the label provided with the -label option. This will considerably slow down the processing, but will avoid data duplication.

  Consider forcing the ipc mode of ClearCase::Argv, with -/ipc=1, and using the BranchOff feature, both of which are relevant to this kind of situation.

• -Narrow

  The -Narrow flag allows a regular expression to limit the files from the source list which are compared with the destination base. I.e. if you want to transport all the *.java files from a dir tree without the class files you can use

      synctree -N '\.java\$' ...

  Note that the argument is a Perl regular expression, not a file glob. Any legal Perl RE may be used. Also, multiple -Narrow flags may be used; thus, to collect *.class and *.properties files you may use either of:

      synctree -N '\.class\$' -N '\.properties\$' ...
      synctree -N '\.(class|properties)\$' ...

  Also, the -Narrow flag is considered only for file lists derived internally by synctree. If you provide your own file list using -flist, filtering it is your own responsibility.

  This RE is automatically made case-insensitive on Windows.

FILE MAPPING

Synctree has lots of support for remapping filenames. The options can be pretty confusing and thus deserve special treatment here.

Filename mapping is enabled with the -map flag. Without -map, a list of files provided on the command line is interpreted as a set of from files; their to paths are derived via s/^sbase/dbase/ and thus the file basenames cannot change. In the presence of -map the arguments are instead interpreted as a hash alternating from and to names. Thus

  synctree -sb /etc -db /vobs_st/etc /etc/passwd /etc/group

would make two files under /vobs_st/etc called passwd and group, whereas

  synctree -sb /etc -db /vobs_st/etc -map /etc/passwd /vobs_st/etc/foo

would create one file (/vobs_st/etc/foo) which is a copy of /etc/passwd. Alternatively the mapping may be specified with a literal =>:

  synctree -sb /etc -db /vobs_st/etc -map '/etc/passwd => /vobs_st/etc/foo' ...

but note that this must be quoted against shell expansion. The => style is also allowed in files specified via -flist, thus:

  synctree -sb /etc -db /vobs_st/etc -flist - << EOF
  /etc/passwd => /vobs_st/etc/foo
  /etc/group  => /vobs_st/etc/bar
  EOF

COMPARISONS

Synctree is comparable to citree and clearfsimport. It is similar to citree but has more options and runs on both Windows (including Cygwin) and UNIX. It has the following advantages over clearfsimport:

• Synctree works with all ClearCase versions whereas clearfsimport is first supported in CC 4.2.

• Synctree is capable of preserving CR's during MVFS->MVFS transfers whereas clearfsimport always treats the source area as flat files.

• Synctree has support for mapping filenames in transit and a -Narrow option for limiting the set of files to transfer.

• Synctree is built on a documented API (ClearCase::SyncTree) which is available for custom tool development in Perl, whereas clearfsimport is a command-line interface only.

• Synctree has support for element reuse. I.e. if an element is added in one pass and removed (rmnamed) in a subsequent pass, and if a third pass would make another element of the same name, synctree can optionally (-reuse) make a link to the existing file instead of creating a new element which might be considered an "evil twin".

• Synctree has support for version reuse. In conjunction with labeling the results, importing a new version may be skipped by labeling instead an existing suitable one, even if not currently selected.

However, unless you need one of the above features the supported, integrated solution (clearfsimport) is generally preferable. And of course some of these features may eventually be supported by clearfsimport; check current documentation.

BUGS

• Subtraction of symlinks is currently unimplemented. This could be made to work, it's just a corner case I haven't gotten to.

• SyncTree does not transport empty directories, and added/removed directories aren't shown explicitly in the list of operations to be performed. This is a structural artifact. It could presumably be fixed by adding an extra phase which looks for empty dirs.

• I have not tested SyncTree in snapshot views and would not expect it to work there without modifications.

DEBUGGING

The special flag -/dbg=1 will cause all underlying cleartool commands to be printed as they are run (this is actually a feature of the Argv module on which synctree is built). Please run in this mode and include all output when reporting problems.

Note also the -/ipc=1 flag, which uses a common background cleartool process, for improved performance. In this mode, cleartool commands are prefixed with => instead of the default +.

AUTHOR

David Boyce <dsbperl AT boyski.com>

COPYRIGHT

Copyright (c) 2000-2010 David Boyce. All rights reserved. This Perl program is free software; you may redistribute and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), "perldoc ClearCase::SyncTree"

cpanm ClearCase::SyncTree

perl -MCPAN -e shell
install ClearCase::SyncTree