fmerge

fmerge(1)                   General Commands Manual                  fmerge(1)



NAME
       fmerge - merge files

SYNOPSIS
       fmerge [ option...  ] basefile fileA fileB

       fmerge -Help

       fmerge -VERSion

DESCRIPTION
       The fmerge program is used to compare the changes between two different
       descendants of a base file, and creates an output file which contains
       both sets of changes.  This is useful when two users both take the same
       version of a file and make independent edits to it, and then later want
       to create a file which contains both sets of edits.  In such a use, the
       original file that both sets of edits is derived from is called the
       base file.  The two files containing the edits are called file A and
       file B.

       The command:
              fmerge basefile fileA fileB -o outputfile
       produces the output file which contains the edits contained in file A
       and file B, based on the base file .  If the -Output option was not
       used, or if no outputfile is specified, then the merged lines are typed
       to the standard output.  The order of specifying file A and file B is
       usually unimportant.

       The fmerge program can also be used to remove earlier edits made to a
       module.  To do this, make the version containing the edits you want to
       delete be the basefile.  Make the version previous to the edit you want
       deleted be file A.  Finally, make the most recent version of the file
       which contains the other edits (including the one you want deleted) be
       file B.  Then the result of merging will be the newest version of the
       module minus the changes made by the edit you wanted removed.  For
       example, if three successive versions of some module have the names
       edit10, edit11 and edit12, and you want the changes done by edit11 to
       be undone, but still want the changes done by edit12, then you use the
       command:
              fmerge edit11 edit10 edit12 -o outputfile

       While merging the two sets of edits, fmerge may discover conflicts.  A
       conflict occurs when the same line of the base file is changed by both
       of the two sets of edits.  The change can be due to new lines being
       inserted, lines being deleted, or both.  When conflicts occur, the
       output file contains conflict identification lines, which are lines
       containing the string '/-/-/-/'.  These lines indicate the region where
       the two sets of edits are incompatible.  You must then edit the output
       file and remove these lines, and in addition correct the conflicts
       manually in order to produce the correct result.

OPTIONS
       The following options are understood:

       -Conflicts [ conflictfile ]
               Since conflicts due to deletions are invisible in the output
               file, and inserts do not specify which of the two edits
               inserted the lines, there is an alternative output format from
               the fmerge program.  This output format describes what happens
               to each line of the base file, so that conflicts are easier to
               detect and fix.  The command:
                      fmerge basefile fileA fileB -c conflictfile
               produces the file describing the results of the merge in
               detail.  If the -Conflicts option is specified without any
               conflictfile name, then the conflicts are send to the standard
               output.

               If there are conflicts, and the -Conflicts options is not
               specified, the fmerge program will exit with a status of 1.

               The conflict file contains lines which contain three characters
               and then some text.  The first three characters describe what
               is happening to the base file at that point.  These characters
               are the following:

                      IA      This line was inserted by file A.

                      DA      This line was deleted by file A.

                      IB      This line was inserted by file B.

                      DB      This line was deleted by file B.

                      <blanks>
                              This line is unchanged.

                      X       This is a conflict identification line.

                      U       There are unspecified unchanged lines here.

               Each set of conflicts is flagged by three identification lines.
               The first line indicates the beginning of the conflict, and
               specifies the line numbers for the base file and two divergent
               files.  The second conflict identification line separates lines
               changed by file A from lines changed by file B.  The third
               conflict identification indicates the end of the conflict.

               You can edit this conflict file to remove the conflicts.  This
               involves deleting the conflict identification lines, and
               changing the conflicting lines as necessary to fix the
               conflict.  While doing this, remember to leave three blank
               characters at the front of any new lines you insert while
               correcting the conflicts.  When you are done, there should be
               no lines which begin with an 'X' in the file.  All other lines
               can remain.  Then you can use the command:
                      fmerge conflictfile -o outputfile
               to create the new output file which has the desired data.  Once
               again, if no -Output option or outputfile is used, the output
               is send to the standard output.

       -Unchanged number
               Besides physical conflicts, there can be logical conflicts.
               These are changes made to different lines in the base file such
               that the program is no longer correct.  Such conflicts cannot
               be detected by a program, and so these must be checked
               manually.  In order to make this process easier, the -Unchanged
               option can be used to reduce the size of the conflict file to
               only include regions near changed lines.  This file can then be
               examined in order to detect possible logical conflicts.  As an
               example, the command:
                      fmerge basefile fileA fileB -c -u 3
               will send to the standard output all changes made by either
               sets of edits, with only three unchanged lines surrounding each
               edit.

               When using the -Unchanged option, the conflict file will
               contain lines starting with 'U'.  These represent unchanged
               lines, and the number following the letter is the number of
               unchanged lines.  The resulting conflict file cannot be read to
               produce an output file because of the missing lines.  If this
               is attempted, an error will be generated.

               It is possible to use both -Output and -Conflicts in the same
               command.  Thus you can produce the output file which you hope
               is correct, and also produce the conflict file which you can
               use to check for logical conflicts.

       -Verbose [ number ]
               This option can be specified with any other action, and outputs
               status information about the progress of the action.  This is
               useful for debugging of problems, or just for amusement when
               the system is slow or a large file is being processed.  It
               accepts a numeric argument to indicate the verbosity for
               output.  The levels are as follows:

               0   No output at all (except for errors).

               1   Single-line output describing action (default).

               2   Detailed status as action proceeds.

       -Failures number
               This option restricts the number of physical conflicts that are
               allowed before failing.  This is used if you are not interested
               in the results if there are too many conflicts.

       -Help
               Give some help on how to use the fmerge program.

       -Ignore
               Ignore conflicts.

       -VERSion
               Show what version of fmerge is running.

       All options may be abbreviated; the abbreviation is documented as the
       upper case letters, all lower case letters and underscores (_) are
       optional.  You must use consecutive sequences of optional letters.

       All options are case insensitive, you may type them in upper case or
       lower case or a combination of both, case is not important.

       For example: the arguments "-help, "-HELP" and "-h" are all interpreted
       to mean the -Help option.  The argument "-hlp" will not be understood,
       because consecutive optional characters were not supplied.

       Options and other command line arguments may be mixed arbitrarily on
       the command line.

       The GNU long option names are understood.  Since all option names for
       fmerge are long, this means ignoring the extra leading '-'.  The
       "--option=value" convention is also understood.

FILE NAME EXPANSION
       As a convenience, if a pathname begins with a period and a environment
       variable exists with that name, then the value of the environment
       variable will be used as the actual pathname.  For example, if a
       environment variable of .FOO has the value this.is.a.long.name, then
       the command
              fmerge -o .FOO
       is actually equivilant to the command
              fmerge -o this.is.a.long.name
       If you want to prevent the expansion of a pathname which begins with a
       period, then you can use an alternate form for the pathname, as in:
              fmerge -o ./.FOO

BINARY FILES
       In general, fmerge can handle all text files you throw at it, even
       international text with unusual encodings.  However, fmerge is unable
       to cope elegantly with files which contain the NUL character.

       The fcomp(1) program simply prints a warning, and continues, you need
       to know that it converts NUL characters into an 0x80 value before
       performing the comparison.

       The fmerge(1) program also converts the NUL character to an 0x80 value
       before merging, after a warning, and any output file will contain this
       value, rather than the original NUL character.

       The fhist(1) program, however, generates a fatal error if any input
       file contains NUL characters.  This is intended to protect your source
       files for unintentional corruption.  Use uuencode for files which
       absolutely must contain NUL characters.

EXIT STATUS
       The fmerge program will exit with a status of 1 on any error.  The
       fmerge program will only exit with a status of 0 if there are no
       errors.

REFERENCES
       This program is based on the algorithm in
              An O(ND) Difference Algorithm and Its Variations, Eugene W.
              Myers, TR 85-6, 10-April-1985, Department of Computer Science,
              The University of Arizona, Tuscon, Arizona 85721.
       See also:
              A File Comparison Program, Webb Miller and Eugene W. Myers,
              Software Practice and Experience, Volume 15, No. 11, November
              1985.

COPYRIGHT
       fmerge version 1.6.D001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999
       Peter Miller; All rights reserved.

       This program is derived from a work
       Copyright (C) 1990 David I. Bell.

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       59 Temple Place, Suite 330, Boston, MA 02111, USA.

AUTHORS
       Peter Miller         Web:   http://www.canb.auug.org.au/~millerp
       /\/\*             E-Mail:   millerp@canb.auug.org.au

       David I. Bell        Web:   uhttp://www.canb.auug.org.au/~dbell
                       Internet:   dbell@canb.auug.org.au



Reference Manual                     FHist                           fmerge(1)