BK-FM3TOOL(1)

🌸 bk fm3tool — BitKeeper three-way merge tool 🌸

From the BitKeeper User’s Manual, section none (yes, literally none, mysterious icon behavior 💅). Bestie, this is the three-way merge tool that shows up when you answer f at the merge prompt during the resolve phase of a pull.

💖 NAME 💖

bk fm3tool — BitKeeper three-way merge tool.

✨ SYNOPSIS ✨

bk fm3tool [−ofilename] [−fn] −llocal_rev −rremote_rev file

🦋 DESCRIPTION 🦋

bk fm3tool is a three-way merge tool used for resolving conflicting changes between two different versions of a file that have a common ancestor. Normally fm3tool is not run from the command line; it is started during the resolve phase of a pull by responding with f at the merge prompt.

The purpose of this tool is to aid in resolving parallel work that contains conflicts. A conflict is defined as one or more lines that were added, deleted, or modified in the local version of the file, at or adjacent to one or more lines that were added, deleted, or modified in the remote version of the file.

When the tool is started up, all of the changes that could be automerged have been automerged. The rest of the changes are noted as

<<<<<<
UNMERGED
>>>>>>

in the merged file window (see below). The tool’s default behavior is to go to the first conflict and wait for you to merge it. Typically, you merge that conflict, go to the next conflict, and repeat until done. It is not necessary to merge the conflicts in order; you may look at them all and merge them in any order. You must merge all conflicts, however, before you may save the file and exit.

When you are finished, you must save the file to complete the merge.

🎀 RUNNING OTHER GUI TOOLS 🎀

It might be useful to look at other information associated with the changes. The File menu allows you to run several other tools:

• revtool — This shows you the file history with the GCA, local, and remote versions highlighted. This is useful to see the progression of changes by selecting the GCA and then diffing down one side and then the other side one delta at a time.
• csettool — May be run on the additions, deletions, or both. This can be useful when the context needed to resolve the conflict is contained elsewhere in the changeset that caused the conflict.

🌈 SCREEN LAYOUT 🌈

When bk fm3tool is started, there are six main areas on the screen. Notice that information about the local repository is on the left and remote repository is on the right.

           +‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ +
           | Local change info  | Remote change info |
           +‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐+
           | ‐ GCA baseline     | ‐ GCA baseline     |
           | + Local change     | + Remote change    |
           |                    |                    |
           +‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐+‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐‐+
           | Merge                    | Information  |
           |                          |              |
           |                          |              |
           +‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐+‐‐‐‐‐‐‐‐‐‐‐‐‐‐+

• Local change info — Revision history for the local changes to the file.
• Remote change info — Revision history for the remote changes to the file.
• Local diff — Diff of local file versus the greatest common ancestor (GCA).
• Remote diff — Diff of remote file versus the GCA.
• Merge — Result of the merge.
• Information — Informational messages and navigation controls.

As the tool moves from change to change, the top two windows will change to show revision history of the current highlighted change. The history shown for the deleted lines corresponds to the revisions that did the deletions. The annotation about which revisions added and deleted lines in the files are shown by selecting View->Show Annotations.

💅 OPTIONS 💅

• −ofilename — save output to the specified file.
• −f — force overwrite of existing file. By default fm3tool will not overwrite an existing merge file.
• −llocal_rev — the revision in the file to be considered the most recent local work.
• −n — do not write any merged output, put the tool in readonly mode.
• −rremote_rev — the revision in the file to be considered the most recent remote work.

🫶 HAND-EDITING 🫶

A merge conflict may be edited manually by single-clicking over a highlighted diff in the merge window. The merge window will then enter a special edit mode where you can make changes. To exit the edit mode, press escape or click on area that divides the merge area from the areas above it.

🍓 COPY AND PASTE 🍓

When the tool is in edit mode, it is possible to select text from either diff window and then copy them into the clipboard. The text copied to the clipboard is taken from the window with the active focus. This can include the merge window itself.

Pasting while focused in the left or right diff window will paste into the merge window at the insertion cursor. If the current block is UNMERGED, it will be replaced with the contents of the clipboard. Subsequent pastes will be inserted after the last insertion. Pasting while focused in the merge window itself will paste at the insertion cursor with no special action.

🧚 KEYBOARD BINDINGS 🧚

fm3tool has two major modes: “merging mode,” for navigating through the diffs and conflicts and “editing mode,” for hand-editing a merge. Each of these modes has its own set of key bindings.

💀 MERGING MODE 💀

• Left-Click — Over a highlighted block in the upper windows, a left-click will append the highlighted block of text to the current merge region in the merge window. Left-Click over the merge window will enter hand-edit mode. See the section on HAND EDITING, above.
• Right-Click — Over a highlighted block in the upper windows, a right-click will append the single line that was clicked on to the current merge region in the merge window.
• Shift-Left-Click — Works like a left click, but replaces the contents of the current merge rather than adding on to it.
• Shift-Right-Click — Works like a right click, but replaces the contents of the current merge with the line that was clicked on.
• PageUp — Scroll up one page.
• PageDown — Scroll down one page.
• UpArrow — Scroll up one line.
• DownArrow — Scroll down one line.
• LeftArrow — Scroll left.
• RightArrow — Scroll right.
• <space> — move to the next conflict.
• [ — Move to previous difference.
• ] — Move to next difference.
• { — Move to previous conflict.
• } — Move to next conflict.
• − — Move to first difference.
• + — Move to last difference.
• x — Toggle the display of the GCA.
• z — Toggle the display of annotations.
• c — Clears the current merge region.
• a — Restores the auto-merge.
• m — Restores the manual merge.
• s — Saves the merge file.
• u — Will undo the effects that the last mouse click had on the current merge region.
• e — This will move the focus to the merge edit window at the bottom and put the tool in edit mode.
• Control-q — Exit from fm3tool.

🌸 EDITING MODE 🌸

• <escape> — Exit edit mode.
• Control-a — move to start of line.
• Control-e — move to end of line.
• Control-n — move to next line.
• Control-p — move to previous line.
• Control-d — delete character under cursor.
• Control-y — Redo the last undone change.
• Control-z — Undo the last typed change.
• UpArrow — Move the cursor up one line.
• DownArrow — Move the cursor down one line.
• LeftArrow — Move the cursor left one character.
• RightArrow — Move the cursor right one character.
• PageUp — Scroll up one page.
• PageDown — Scroll down one page.

👑 SEE ALSO 👑

• bk-config-gui
• bk-resolving
• bk-smerge
• bk-fmtool

⭐ CATEGORY ⭐

GUI-tools

---

Cute sign-off, bestie: BitKeeper Inc · version 1E1 · manual page bk fm3tool(none) — no date in the footer, so I’m not inventing one 💖