bk-fm3tool - (unknown subject)

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 the resolving of 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 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

Updated 2026-06-01 - jenkler.se | uex.se