Provided by: fhist_1.18-1_amd64 bug

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 all conflicts.

       -Ignore_Identical_Conflicts
               The option may be used to suppress conflicts  which  make  identical  deletes,  or
               identical inserts, or identical changes.  This is often desirable when merging two
               source code branches.

       -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 -BINary 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.18.D001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997,  1998,  1999,  2000,  2001,  2002,
       2003, 2004, 2005, 2006, 2008, 2009 Peter Miller;

       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 3 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, see <http://www.gnu.org/licenses/>.

AUTHORS

       Peter Miller       Web:   http://miller.emu.id.au/pmiller/
       /\/\*           E‐Mail:   pmiller@opensource.org.au

       David I. Bell      Web:   http://www.canb.auug.org.au/~dbell
                       E‐Mail:   dbell@canb.auug.org.au