#-------------------------------------------------------------------------
# Copyright 2006 Kyle Turner.
#
# License is hereby granted to use this software and distribute it
# freely, as long as this copyright notice is retained and modifications 
# are clearly marked.
#
# ALL WARRANTIES ARE HEREBY DISCLAIMED.
#
# $Id: //guest/kyle_turner/perforce/resolve/README.txt#1 $
#-------------------------------------------------------------------------
#
# Sample P4 API C++ program which extends the normal "p4 resolve" command.
#
# The GNU makefile is set up for Linux and Windows.  For Windows you will
# need the make and unix like tools from www.cygwin.com or equivalent.
#
# To build run:  make P4API=<dir>
#
# You can also edit the Makefile to set the P4API correctly.
#
# Below is the help text from "resolve -h" which goes into more detail.
#-------------------------------------------------------------------------

    resolve -- Extension of 'p4 resolve' giving extra weight to
               the external merge program specified with $P4MERGE.

    resolve [ -ax -fx -k -n ] [ file ... ]

        Alters the normally interactive 'p4 resolve [ file ...]' by
        running the external merge on every file and then resolving
        only if the external merge finds no conflicts.  Here is a
        table of the actions:

            External merge finds conflict       -> skip
            Internal merge finds conflict       -> skip (unless -fx)
            Only their or both changes          -> accept theirs
            Only your or both changes           -> accept yours
            External and internal merges same   -> accept merge
            Otherwise use external merge        -> accept edit

        Conflicts in the external merge are found by searching for
        lines starting with '<<<<' in the merge result file.  If
        the merge flags the conflict with any other string the
        program will need to be enhanced.

        The external merge can be specified with the P4MERGE
        environment variable like (using /bin/sh syntax):

            P4MERGE='<merge-program>'
            P4MERGE1='<merge-program> %base% %their% %your% %result%'

        The 'p4 resolve' only supports the first usage without variable
        expansion.  The second form can be used to rearrange the
        arguments and reduce the overhead of running an extra shell
        script.  For example:

            P4MERGE1='merge3 -o "%result%" "%their%" "%base%" "%your%"'

        switches the argument order of the arguments and specifies the
        type of quotes needed to allow spaces in file names.

        The -ax specifies 'accept external' which is the flow describe
        above.  It currently is the default and will only need to be
        specified if the program is extended to include all the
        'p4 resolve' options.

        The -fx specifies 'forces external' and directs the program
        to accept the external merge if it has no conflicts but the
        internal merge does.  The external merge will be resolved
        with 'accept edit' to get the correct crediting.

        The -k specifies 'keeps temp files' and can be used for
        debugging or developing additional scripts.  The files are
        saved at:

            <path>/_restmp/<file>/base
                                  your
                                  their
                                  merge
                                  xmerge

        Note that the <file> name as a directory which looks odd but
        simplifies scripting.  For example to compare all the merges:

             for tmp in `find . -name _restmp -print`; do
                 for f in $tmp/*; do
                     diff -q $f/xmerge $f/merge
                 done
             done

        The resolve program does not remove the _restmp directories
        so they must be removed by hand or script.  Also if run twice
        with -k the previous files will be overwritten.  If you want
        the 'your' file as a backup this should be avoided.

        [Aside:  One possible enhancement would be to implement a two
        phase resolve.  The first phase would be setup using '-k -n'
        and then after all the files were correctly merged a new
        option could take the results and submit the resolves to the
        server.]

        The -n specifies that the program should do all the work
        and then do a 'skip' rather than accept any resolve.