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