/ 
ClearCase-SyncTree-0.19
River stage zero No dependents
/ synctree

NAME

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

SYNOPSIS

Run this script with the -help option for usage details. Here are some additional sample usages with explanations:

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

[Take all files located under /tmp/newcode/xxx, remove the leading "/tmp/newcode", from each of their pathnames, and place the remaining relative paths under "/vobs_tps/xxx". Check in when done.]

synctree -cr -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.]

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 for 'here' and 'there'.

DESCRIPTION

Brings a VOB area into alignment with a specified set of files from a source area. This is analogous in some ways to clearexport_* and clearimport but those cannot work incrementally; they do an all-or-nothing import. 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 files from a nightly build to a release VOB while preserving CR's, 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>. The -rmname flag will cause this removal to happen as well.

This script must run in a view context; the branching behavior of any checkouts it makes will be governed by the view's config spec. Also, the directory named by the -dbase flag must exist and lie under a mounted VOB tag.

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 @ARGV will be traversed recursively. If no source-file-list is provided at all, the directory specified with -sbase is treated as the default.

File paths may be given as relative or absolute; all filenames are turned into absolute paths, then the path given with the -sbase parameter is removed and replaced with that of -dbase to produce the destination pathname.

Symbolic links are supported, even on Windows. Note that the text of the link is transported verbatim from source area to dest area; thus relative symlinks may no longer resolve in the destination.

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

FILE MAPPING

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

All 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 do not change. However, in the presence of -map the @ARGV is instead interpreted as a hash alternating from and to names. Thus

synctree -sbase /etc -dbase /vobs_etc /etc/passwd /etc/group

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

synctree -sbase /etc -dbase /vobs_etc -map /etc/passwd /vobs_etc/foo

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

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

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

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

COMPARISONS

Synctree is comparable to citree and clearfsimport. It is similar to citree but runs on both Windows and UNIX. It has the following advantages over clearfsimport:

  • Synctree works with ClearCase versions prior to 4.1.

  • Synctree handles MVFS-MVFS> transfers while preserving CR's whereas clearfsimport does flat_file_system-MVFS> only.

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

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

  • Synctree may at some point (but does not yet) have support for element retention. 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 could optionally make a link to the existing file instead of creating what might be a "evil twin".

However, unless one of the above applies the supported, integrated solution (clearfsimport) is generally preferable. And of course all of these features may eventually be supported by clearfsimport.

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).

AUTHOR

David Boyce <dsb@world.std.com>

COPYRIGHT

Copyright (c) 2000 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.

STATUS

This is currently ALPHA code and thus I reserve the right to change the UI incompatibly. At some point I'll bump the version suitably and remove this warning, which will constitute an (almost) ironclad promise to leave the interface alone.

PORTING

The guts of this program are in the ClearCase::SyncTree module, which is known to work on Solaris 2.6-7 and Windows NT 4.0SP3-5, and with perl 5.004_04 and 5.6. The synctree wrapper program per se has had only rudimentary testing on Windows but appears to work fine there.

SEE ALSO

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