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