• abort
• backups
• bk
• bkd
• changes
• check
• citool
• clone
• cmdlog
• collapse
• commit
• conflicts
• cset
• csets
• csettool
• difftool
• files
• fixtool
• glob
• history
• id
• import
• level
• lock
• makepatch
• merge
• merge-binaries
• parent
• pending
• pull
• push
• relink
• repocheck
• resolve
• resolving
• revtool
• rm
• rmgone
• service
• setup
• setuptool
• sfio
• status
• superset
• tag
• tags
• takepatch
• templates
• triggers
• undo
• unlock
• unpull
• untag
• url

bk resolving(7.3ce)         BitKeeper User's Manual        bk resolving(7.3ce)

NAME
       bk resolving - help on resolving conflicts

DESCRIPTION
       This  section  documents  the merge process started by the resolve com-
       mand.  See bk resolve for details on using resolve.

       While in resolve, you can press ENTER to see a summary of the commands.

       The bk resolve command prompts you on each file that has conflicts.   A
       conflict is defined as two deltas made in parallel in different reposi-
       tories.  If the conflict does not have any overlapping lines,  then  it
       may have been automerged, depending if bk resolve was run with the "-a"
       option.

       There are other sorts of conflicts besides  the  typical  file  content
       conflicts.   BitKeeper manages file names, permissions, flags, and sym-
       bolic tags in the same way as it manages  file  contents.   That  means
       that  you  can  have a permissions conflict if, for example, one person
       changed the file to 0755 mode and another changed it to 0777 mode.

       The resolve process for all conflicts is fairly similar.  For each type
       of  conflict on each file, you will be prompted for an action.  To view
       a brief summary of the conflict and a list of available actions,  press
       ENTER  (or  ?   or  help).  The choices usually include a more detailed
       explanation of the situation; we try to consistently make  this  avail-
       able as the "x" command (as in eXplain).

       Some  of  the  available actions allow you to diff the files, view file
       history, and merge using graphical tools, etc.  See the command summary
       for the full list.

MULTIPLE USERS
       Only  one  user is allowed to run the resolver at any given time.  If a
       second user attempts to run bk resolve, they will get an error  message
       indicating that another user is already running the resolver.

       It  is also possible to have multiple users resolve a set of conflicts.
       A typical way to do this is to use the bk conflicts command  to  get  a
       list  of  files  that  need manual resolving along with a list of users
       responsible for the conflicting changes.  Then each  user  takes  turns
       invoking the resolver on the list of files for which they are responsi-
       ble, checking in the changes as they go.  After the  conflicts  in  the
       individual files have been resolved and checked in, the bk resolve com-
       mand is run with no arguments in order to finish the process and commit
       a  changeset.  The changes for each file will be attributed to the user
       that committed that particular file.  The changeset will be  attributed
       to the user that does the final commit of the changeset.

       In  this  context,  as  well  as  the single user case, it is sometimes
       desirable to quit the resolver and restart it at a  later  time.   When
       the  resolver is re-invoked, it will not ask the user to re-merge files
       that have already been resolved and will continue where the  user  left
       off  on  the previous invocation.  This process can be repeated as many
       times as desired until all conflicts have been resolved.

VIEW DIFFERENCES AND HISTORY
       To see the diffs use the "d" command.  For side-by-side diffs, use  the
       "sd"  command.  You can also diff one or the other branches against the
       common ancestor using "dr" or "dl".  Type "D" to get a graphical, color
       coded side-by-side diff browser.

       There  are  also built-in commands to show the history of the file (see
       "h", "hl", "hr").  In addition,  "p"  starts  the  the  graphical  file
       browser  which  allows  you  to view the difference between versions by
       clicking the left button on the earlier rev and the right button  on  a
       later  rev.  The bottom of the screen will show the diffs.  If you type
       Return at the prompt, the three revisions forming the merge are part of
       the help message.

MERGING CONTENTS
       When  in  resolve, there are four different files for each merge.  They
       are:

       local  The version of the file in the local repository.
       remote The version of the file in the other repository.
       merge  The merged file.
       GCA    A common ancestor of the local/remote versions.

       Your goal is to generate the merge file using one of the methods below.

       The easiest and most popular merge method is to use the "m" command for
       cases  where  there  are  no  overlapping lines. This method performs a
       three-way diff and merge and  warns  you  when  there  are  overlapping
       lines.   If  there  are overlaps, you have to edit the merged file (use
       the "e" command), find the conflict markers which look like  "<<<<"  or
       ">>>>",  and  manually  fix  the conflicts.  This command requires care
       since non-overlapping lines does not mean that the merge makes semantic
       sense.

       If the merge looks complicated, a good approach is to start up the file
       browser with "p" and then start up a side-by-side filemerge  with  "f".
       Then  walk  through the diffs, picking and choosing with blocks of code
       to use.  If you get confused about who added what, you can  go  to  the
       history tool browser (bk revtool) and left click on the common ancestor
       and right click on each of the two tips of the trunk/branch to see  who
       added what.

       It  is  also  possible  to use a combination of graphical tools and the
       automatic merge.  You can type "p" to run the file browser, "D" to  run
       difftool,  "m"  to  do the merge, and then "e" to edit the merged file.
       The file browser is run in the background so you can look at the  vari-
       ous  changes as described above.  Warning: if you are running your edi-
       tor and the file merge program, then both are working on the same  out-
       put  file and whichever one writes it last, overwrites any earlier ver-
       sions.

       You may also call an external tool  to  merge  changes.   When  in  the
       resolver, if you say

           file.c>> !<command>

       then  <command>  will  be  run with the following environment variables
       set:

       BK_LOCAL  pathname of a temp file containing the local version
       BK_GCA    file containing the common ancestor
       BK_REMOTE pathname of a temp file containing the remote version
       BK_MERGE  pathname where the merged content should be placed

COMMIT
       The merge process is not complete until you commit the  file  with  the
       "C" command at the resolve prompt.  This means you can merge repeatedly
       until you are happy with the results.  Each time you  merge  and  save,
       however, you overwrite the previous merge attempt.

       When you are happy with your merged file, click done in filemerge, exit
       the file browser, and type "C" at the prompt to  commit  the  file  and
       move on to the next one.

SEE ALSO
       bk conflicts
       bk fm3tool
       bk fmtool
       bk merge
       bk resolve
       bk revtool
       bk smerge

CATEGORY
       Overview
       Repository

BitKeeper Inc                         1E1                  bk resolving(7.3ce)