xenial (1) fmerge.1.gz

Provided by: fhist_1.18-2_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.

       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