WHAT IT IS

This is a program/module for bringing a set of files under ClearCase
control by making the minimal set of required changes and running the
minimal set of cleartool operations. The real code is in the module,
but a wrapper script 'synctree' is provided for command-line access.
This is a distant descendant of Paul Smith's 'citree' program, which in
turn is derived from a sample shell script of the same name shipped
with ClearCase. Though SyncTree bears no resemblance to either one any
more, I retain Paul's copyright since mine did mutate from his.

The most common use for SyncTree is probably in moving the results of a
build from their build locations to a staging area or release VOB while
preserving CR's and potentially changing names/paths en route.  That's
the purpose it was originally designed for.

Full documentation for both module and program is provided as inline
POD format.

Note that there's also a Rational-supported CC program 'clearfsimport'
which does part of what synctree does.

			DIFFERENCES FROM CITREE

Differences between synctree and citree include:

1. Synctree works on Windows as well as UNIX.
2. Synctree is capable of preserving CR's when checking in DO's.
3. Synctree has an exception-handler implementation which by default
   will undo all work upon encountering an error (it's a matter of
   opinion whether this is a feature but anyway it can be turned off).
4. The CLI is different, though the flag semantics map fairly well.

			DIFFERENCES FROM CLEARFSIMPORT

As of ClearCase 4.2 there's a new 'clearfsimport' tool which will have
the effect of obsoleting citree and many uses of synctree. However
there remain some cases where synctree may be preferred. For instance:

1. Synctree works with CC versions prior to 4.2.

2. Synctree can preserve CR's during MVFS->MVFS transfers whereas
clearfsimport does flat_file_system->MVFS only (more properly, it
treats the source as flat files whether they are or not).

3. Synctree has support for remapping filenames "en passant" and a
-Narrow option for limiting the set of files to transfer via
regular expression.

4. A Perl API (ClearCase::SyncTree) is provided for custom tool
development whereas clearfsimport is a command-line interface only.

5. Synctree supports "element retention". I.e. if an element is added
in one pass and then removed (rmnamed) in a subsequent pass, and if a
third pass would make another element of the same name, synctree can
optionally (with the -reuse flag) link to the existing element instead
of creating what might be considered an "evil twin".

6. Synctree supports "version reuse", i.e. is able to label and
existing version, albeit not originally selected by the config spec,
instead of creating a duplicate of it. This feature is especially
useful if one imports the 'merge result' of two releases imported
previously. In such a case, it is impossible to select a single
baseline which would be optimal for all the elements.

7. Clearfsimport has an unfortunate behavior relating to timestamps and
repeated imports and -nsetevent; see this URL:
<http://www.cmcrossroads.com/cgi-bin/cmwiki/view/CM/BccFaq1_2_16> for
details.

8. SyncTree supports branching off the root of the version tree
instead of from the selected version, as driven by the BranchOff view
attribute in the config spec. Clearfsimport cannot be made to respect
this strategy.

9. And of course SyncTree is freeware, with all the attendant
advantages (fix it yourself) and disadvantages (fix it yourself).

But in some cases a supported, integrated solution is to be preferred
and clearfsimport also has advantages over synctree which aren't
discussed in depth here, such as mastership handling (-master) and the
ability to go somewhat deeper into the database than an aftermarket
tool can (see -nsetevent).  And of course it doesn't require you to
have various Perl modules installed. See the clearfsimport
documentation for its details.

			PLATFORM NOTES

This package is believed to work on all ClearCase platforms including
Windows, and even Cygwin. Note, however, that the test environments
are mostly Solaris 10 and Windows Vista, Perl 5.8.8 to 5.12.0. It
worked on Solaris 7 and NT 4.0 with Perl 5.6.0 when I last worked
there but I have no way to check these or any other platforms now.

A sample "synctree.bat" script is provided showing one method of
invocation on Windows. Other ways (for instance using the .pl file
extension association) are also possible.

			LATEST VERSION

The latest released version will always be on CPAN, e.g.
http://www.perl.com/CPAN-local/modules/by-module/IPC/DSB/