==========================================================
CONTRIBUTOR:    Hungtau Ting and Atria Engineering Staff
==========================================================

**********************************************************
************** THIS IS UNSUPPORTED SOFTWARE **************
**********************************************************

**********************************************************
*  Atria makes no representation that the descriptions   *
*   and software code contained in this document will    *
*   not infringe on existing or future patent rights,    *
*     copyrights, trademarks, trade secrets or other     *
*        proprietary rights of third parties. The        *
*     descriptions contained herein do not imply the     *
*  granting of licenses to make, use, sell, license or   *
*  otherwise transfer Atria products described herein.   *
*  Atria disclaims responsibility for errors which may   *
*  appear in this document, and it reserves the right,   *
*   in its sole discretion and without notice, to make   *
*  substitutions and modifications in the products and   *
*         practices described in this document.          *
**********************************************************

---------------------------------------------------
T0006: DIRECTORY AND FILE MERGERS, DIRECTORY 'DIFF'
---------------------------------------------------

DIRECTORY AND FILE MERGERS
--------------------------

These scripts implement a procedure for completely merging
a branch version of a directory. This includes a merger of the
directory element itself, and mergers of file elements, as necessary.

Usage: ct_dirmerge [-c comment] [-i] [-n] [-v] VOB_dir fromBranch toBranch
    -c comment      Checkout comment for merge target
    -i              Ask whether to merge each file
    -n              No execution mode, Print commands but not execute them
    -v              Verbose mode.

If Merge targets are directories, uses "cleartool ln" to merge
since ... quoted from Cleartool man page ln(1):

    "This ClearCase  release  does  not  support  true  directory
    mergers.  However,  you  can  use the ln command to simulate
    such a merger."

The cleartool command sequences to merge directory objects from
fromBranch to toBranch looks like the following, for more info,
see ClearCase manual page ln(1).

    cleartool find VOB_dir -nxname -type d -element 'needs_merge
            ($fromBranch, $toBranch)' -print > /tmp/DirList
    foreach i (`cat /tmp/DirList`)
      ct_diffdir $i$xnsuffix$toBranch/LATEST $i$xnsuffix$FromBranch/LATEST
            > /tmp/missingLinks
      cleartool checkout $i$xnsuffix$toBranch
      if (not identical, i.e. /tmp/missingLinks is not empty) then
        foreach j (`cat /tmp/MissingLink`)
            cleartool ln $i$xnsuffix$fromBranch/LATEST/$j $i
            if ( -d $j) then
                ct_dirmerge ....
            endif
        end
      endif
      cleartool merge -ndata -to $i $i$xnsuffix$fromBranch/LATEST
      cleartool checkin $i$xnsuffix$toBranch
    end

There are four conditions when merging directories.

    same filename   same OID   result       action  side-effect
    -------------   --------   ------       ------  -----------
    True            True       identical    none    none

    True            False      new element          old filename
                               using old    link    no longer accessible
                               filename

    False           True       renamed      link    old filename still
                                                    exists

    False           False      new element  link    none




'DIFF' UTILITY FOR DIRECTORY VERSIONS
-------------------------------------

The "ct_diffdir" script compares two versions of the current working
directory, which must be a ClearCase directory element.

Usage:

  ct_diffdir  [ <old-dir-version> <new-dir-version> ]

* If you don't specify any arguments, these two versions are compared:

  - your current view's checked-out version of the directory
  - the predecessor of this checked-out version

  (An error occurs if your current view does not have the current
  directory checked-out.)


* If you specify directory version arguments, you can include or
  omit "/main/". Thus, the following commands are equivalent:

  % ct_diffdir 4 7
  % ct_diffdir /main/4 /main/7

  And the following commands are also equivalent:

  % ct_diffdir 4 bugfix/2
  % ct_diffdir /main/4 /main/bugfix/2

  



SCRIPTS
-------

ct_dirmerge (Hungtau Ting)
        merge two versions of a specified directory element: the LATEST
        versions on two specified branches. This script must be run
        recursively, until it says there are no more directories to merge.

ct_filemerge (Hungtau Ting)
        merge all file elements in a specified directory, using the
        LATEST versions on specified branches as the "from" and "to".
        The mergers are performed with "merge" or "xmerge", depending
        on the environment variable CLEARCASE_XMERGE.

ct_diffdir (Atria Engineering Staff)
        compare two versions of the current working directory,
        reporting entries that have been added, deleted, or renamed.
        The ct_dirmerge script uses ct_diffdir, but only processes
        entries that have been added or renamed on the "from"
        branch. It ignores deletions on the "from" branch.