BK-SMERGE(1)

💅 bk smerge 💅

hey bestie, welcome to the bk smerge(none) page from the BitKeeper User’s Manual — it’s giving smart text‐based 3‐way file merge energy, and we’re gonna get you all the deets 🫶✨

🌸 NAME 🌸

bk smerge — smart text‐based 3‐way file merge. periodt 💖

✨ SYNOPSIS ✨

bk smerge [−2efghn] [−An] [−an] −llocal −rremote file

💖 DESCRIPTION 💖

okay so the bk smerge command compares the three versions of the file and identifies 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 they’re 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. slay ✨

the bk smerge command does not use the traditional diff3(1) merge. there are a number of heuristics in the default enabled merge algorithms 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.

🚨 bestie, real talk: smerge can only be run on SCCS files. no cap.

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 separated 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. iconic 💅
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 traditional 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 substitution in both the local and remote versions of the file. a substitution 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 unmodified 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. ngl, that’s the tea ☕

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 region is identified, 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. iykyk 👀

💅 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 confuses people the first time they see it. lowkey fair tbh.
• −n — enable the ’newonly’ output format. (like −2 except it marks added lines).
• −e — print examples of all 4 output formats from bk smerge.
• −an — enable merge functions n, where n is a comma separated list of automerge algorithms specified by number. −aall will enable all automerge algorithms. use bk smerge −h to find the algorithms enabled by default.
• −An — disable merge functions n, where n is a comma separated list of automerge algorithms specified by number. −Aall 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 🔥

diff3(1), bk‐resolve, bk‐resolving, bk‐merge

🌈 CATEGORY 🌈

Utility

---

that’s the whole vibe, bestie 💖 xoxo from BitKeeper Inc, version 1E1, bk smerge(none) — bye! ✨🫶