bk fm3tool(7.3ce) BitKeeper User's Manual bk fm3tool(7.3ce)
NAME
bk fm3tool - BitKeeper three-way merge tool
SYNOPSIS
bk fm3tool [-o<filename>] [-fn] -l<local_rev> -r<remote_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 modi-
fied 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 con-
flicts, 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 pro-
gression 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 con-
tained 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 ances-
tor (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 Annota-
tions.
OPTIONS
-o<filename> save output to the specified file.
-f force overwrite of existing file. By default fm3tool
will not overwrite an existing merge file.
-l<local_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.
-r<remote_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 high-
lighted 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. Sub-
sequent 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
BitKeeper Inc 1E1 bk fm3tool(7.3ce)
GUI-tools