bk smerge(7.3ce)            BitKeeper User's Manual           bk smerge(7.3ce)

NAME
       bk smerge - smart text-based 3-way file merge

SYNOPSIS
       bk smerge [-2efghn] [-A<n>] [-a<n>] -l<local> -r<remote> <file>

DESCRIPTION
       The bk smerge command compares the three versions of the file and iden-
       tifies all changes by either the local or the  remote  version  of  the
       file  compared  to the greatest common ancestor (gca).  These groups of
       changes are known as conflict regions and are bounded by a line that is
       identical in all three versions at the beginning of the conflict region
       and at the end of the conflict region.  For each region, one or more of
       the  automerge algorithms (see below) are run to see if the changes may
       be merged automatically.

       The bk smerge command does not  use  the  traditional  diff3(1)  merge.
       There  are  a  number  of heuristics in the default enabled merge algo-
       rithms which help determine regions which are safe to automerge.  These
       can simplify and resolve many conflict regions that can not be resolved
       in the traditional diff3(1) merge.  Please note, smerge can only be run
       on SCCS files.

       In  some  scripts  users  may  want to call smerge directly.  If so, an
       example for usage is:

           bk smerge -g -l1.661 -r1.660.1.4 slib.c > slib.c.merged

       where 1.661 is the local revision and 1.660.1.4 is the remote revision,
       slib.c  is  the  file name and slib.c.merged is the file to which merge
       output is redirected.

       The string for the  local  or  remote  versions  of  the  file  can  be
       expressed  in  the  form  "rev+includes-excludes" where rev is a normal
       revision number like "1.661" and includes and excludes are a comma sep-
       arated  list if revisions to include or exclude from the base revision.
       (The include and/or exclude lists can be omitted if they are empty.)

MERGE ALGORITHMS
       Each of the automerge algorithms is described below.  Currently, all of
       these  are  run by default, but that may change in the future.  Any mix
       of these may be selectively enabled or disabled.

       1. Merge identical changes made by both sides
           If both the local and the  remote  files  have  made  an  identical
           change  to  the GCA, then this function will resolve the region and
           replace it with the new text.
       2. Merge when only one side changes
           This code finds conflict regions where only the local or the remote
           version  has  made  any  changes.   In  this  case  the conflict is
           resolved and the side that made changes is kept.  This is the  tra-
           ditional diff3(1) type automerge algorithm.
       3. Merge adjacent, non-overlapping modifications on both sides
           This  code attempts to find a conflict consisting of a text substi-
           tution in both the local and remote versions of the file.   A  sub-
           stitution  is  a  line  or  group of lines that is deleted and then
           replaced with zero or more lines.  If there is  a  conflict  region
           that  contains lines substituted in the local file that are unmodi-
           fied in the remote and there are lines substituted  in  the  remote
           file that are unmodified in the local file, then a merge of the two
           substitutions is performed.

           Here is an example of a conflict region (in the "-g" output format)
           where this algorithm will successfully resolve the conflict.

               <<<<<<< local slib.c 1.642.1.6 vs 1.645
                    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
               -    assert(sc->tree);
               -    sccs_sdelta(sc, sc->tree, file);
               +    assert(HASGRAPH(sc));
               +    sccs_sdelta(sc, sccs_ino(sc), file);
               <<<<<<< remote slib.c 1.642.1.6 vs 1.642.2.1
               -    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
               +    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
                    assert(sc->tree);
                    sccs_sdelta(sc, sc->tree, file);
               >>>>>>>

           The block after the resolve will be:

                    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
                    assert(HASGRAPH(sc));
                    sccs_sdelta(sc, sccs_ino(sc), file);

           Multiple substitutions are not yet handled.
       4. Merge identical changes at the start of a conflict
           This  code  recognizes one or more lines at the beginning the local
           and remote versions of a conflict region that  are  identical.   If
           there  is  a  block  of lines that are identical then the region is
           split into two regions with the identical  lines  in  a  region  by
           themselves.  This block will later be resolved by algorithm #1.
       5. Merge identical changes at the end of a conflict
           This  is  similar  to  algorithm  #4, except it looks for identical
           lines on both sides at the end of the conflict region.
       6. Merge identical deletions made by both sides
           If both the local and remote version of a region have  deleted  the
           same  non-zero  block of lines at the end of the region, then split
           the region into two with the deletions in a separate  region.   The
           deletions will then get autoresolved.

       When  a conflict regions is identified, then the enabled algorithms are
       run on the block repeatedly until the block is resolved or  no  further
       progress is made.

       Default conflict output format is as follows:

           <<<<<<< gca slib.c 1.642.1.6
                sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
                assert(sc->tree);
                sccs_sdelta(sc, sc->tree, file);
           <<<<<<< local slib.c 1.645
                sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
                assert(HASGRAPH(sc));
                sccs_sdelta(sc, sccs_ino(sc), file);
           <<<<<<< remote slib.c 1.642.2.1
                sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
                assert(sc->tree);
                sccs_sdelta(sc, sc->tree, file);
           >>>>>>>

       Lines  with  "<<<<<<<" indicate the file the conflict region is from in
       the form: <<<<<<< <label> <file> <revision> followed  by  the  conflict
       lines  from  that file.  The end of the conflict region is indicated by
       ">>>>>>>".  Examples of conflict output can be viewed by using the "-e"
       option.

OPTIONS
       -2     Enable the 2 way output format (like diff3(1)).
       -g     Enable 'gca' output format that shows the local and remote files
              like a unified diff between the GCA and that file.  This is  the
              recommended  output  format, but not the default because it con-
              fuses people the first time they see it.
       -n     Enable the 'newonly' output format.  (like "-2" except it  marks
              added lines).
       -e     Print examples of all 4 output formats from bk smerge.
       -a<n>  Enable  merge functions <n>, where <n> is a comma separated list
              of automerge algorithms specified  by  number.   "-a<all>"  will
              enable all automerge algorithms.  Use "bk smerge -h" to find the
              algorithms enabled by default.
       -A<n>  Disable merge functions <n>, where <n> is a comma separated list
              of  automerge  algorithms  specified  by number.  "-A<all>" will
              turn off all automerging.
       -f     Enable fdiff output.  (Used internally by bk fm3tool)
       -h     Display automerge algorithms  by  number  that  are  enabled  by
              default.   If  used  in conjunction with "-a" or "-A", asterisks
              denote enabled algorithms.

EXIT STATUS
       bk smerge returns exit status:

       0   if there were no conflicts
       1   if there were conflicts
       2   if an error occurred

SEE ALSO
       bk resolve
       bk resolving
       bk merge

CATEGORY
       Utility

BitKeeper Inc                         1E1                     bk smerge(7.3ce)