.lf 1 ./lib/en/man1/fmerge.1
'\" t
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1993, 1994, 1998, 1999, 2005, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.ds n) fmerge
.TH \*(n) 1 FHist "Reference Manual"
.SH NAME
\*(n) \- merge files
.if require_index \{
.XX "fmerge(1)" "merge competing file edits"
.\}
.SH SYNOPSIS
.B \*(n)
[
.IR option ...
]
.I basefile
.I fileA
.I fileB
.sp
.B \*(n)
.B \-Help
.sp
.B \*(n)
.B \-VERSion
.SH DESCRIPTION
The
.I \*(n)
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
.IR "base file" .
The two files containing the edits are called
.I "file A"
and
.IR "file B" .
.PP
The command:
.RS
\*(n) basefile fileA fileB \-o outputfile
.RE
produces the output file which contains the edits contained in
.I "file A"
and
.IR "file B" ,
based on the
.I "base file".
If the
\fB\-Output\fP
option was not used,
or if no outputfile is specified,
then the merged lines are typed to the standard output.
The order of specifying
.I "file A" and
.I "file B"
is usually unimportant.
.PP
The
.I \*(n)
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
.IR "edit10" ,
.I "edit11"
and
.IR "edit12" ,
and you want the changes done by
.I "edit11"
to be undone,
but still want the changes done by
.IR "edit12" ,
then you use the command:
.RS
\*(n) edit11 edit10 edit12 \-o outputfile
.RE
.PP
While merging the two sets of edits,
\*(n) 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
.IR "'/\[mi]/\[mi]/\[mi]/'" .
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.
.SH OPTIONS
The following options are understood:
.TP 8n
\fB\-Conflicts\fP [ \fIconflictfile\fP ]
.br
.RS
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
.I \*(n)
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:
.RS
\*(n) basefile fileA fileB \-c conflictfile
.RE
produces the file describing the results of the merge in detail.
If the
\fB\-Conflicts\fP
option is specified without any conflictfile name,
then the conflicts are send to the standard output.
.PP
If there are conflicts,
and the
\fB\-Conflicts\fP
options is not specified,
the
.I \*(n)
program will exit with a status of 1.
.PP
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:
.RS
.TP 8n
IA
This line was inserted by file A.
.TP 8n
DA
This line was deleted by file A.
.TP 8n
IB
This line was inserted by file B.
.TP 8n
DB
This line was deleted by file B.
.TP 8n
<blanks>
This line is unchanged.
.TP 8n
X
This is a conflict identification line.
.TP 8n
U
There are unspecified unchanged lines here.
.RE
.PP
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.
.PP
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:
.RS
\*(n) conflictfile \-o outputfile
.RE
to create the new output file which has the desired data.
Once again,
if no
\fI\-Output\fP
option or outputfile is used,
the output is send to the standard output.
.RE
.TP 8n
\fB\-Unchanged\fP \fInumber\fP
.br
.RS
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
\fB\-Unchanged\fP
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:
.RS
\*(n) basefile fileA fileB \-c \-u 3
.RE
will send to the standard output all
changes made by either sets of edits,
with only three unchanged lines surrounding each edit.
.PP
When using the
\fB\-Unchanged\fP
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.
.PP
It is possible to use both
\fB\-Output\fP
and
\fB\-Conflicts\fP
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.
.RE
.TP 8n
\fB\-Verbose\fP [ \fInumber\fP ]
.br
.RS
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:
.TP 4n
0
No output at all (except for errors).
.TP 4n
1
Single\[hy]line output describing action (default).
.TP 4n
2
Detailed status as action proceeds.
.RE
.TP
\fB\-Failures\fP \fInumber\fP
.br
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.
.lf 1 lib/en/man1/o_help.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.TP 8n
.B \-Help
.br
Give some help on how to use the
.I \*(n)
program.
.lf 290 ./lib/en/man1/fmerge.1
.TP
\fB\-Ignore\fP
.br
Ignore all conflicts.
.TP
\fB\-Ignore_Identical_Conflicts\fP
.br
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.
.lf 1 lib/en/man1/o_version.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.TP 8n
.B \-VERSion
.br
Show what version of
.I \*(n)
is running.
.lf 301 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/o__rules.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1991-1994, 1998, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.PP
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.
.PP
All options are case insensitive,
you may type them in upper case or lower case or a combination of both,
case is not important.
.PP
For example:
the arguments "\-help, "\-HELP" and "\-h" are
all interpreted to mean the \fB\-Help\fP option.
The argument "\-hlp" will not be understood,
because consecutive optional characters were not supplied.
.PP
Options and other command line arguments may be
mixed arbitrarily on the command line.
.br
.ne 4
.PP
The GNU long option names are understood.
Since all option names for
.I \*(n)
are long,
this means ignoring the extra leading '\-'.
The "\fB\-\fIoption\fB=\fIvalue\fR" convention is also understood.
.lf 302 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/z_fne.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.br
.ne 1i
.SH 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
.I ".FOO"
has the value
.IR "this.is.a.long.name" ,
then the command
.RS
.nf
\*(n) \-o .FOO
.fi
.RE
is actually equivilant to the command
.RS
.nf
\*(n) \-o this.is.a.long.name
.fi
.RE
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:
.RS
.nf
\*(n) \-o ./.FOO
.fi
.RE
.lf 303 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/z_binary.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1999, 2000, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.br
.ne 2i
.SH BINARY FILES
In general, \*(n) can handle all text files you throw at it, even
international text with unusual encodings.  However, \*(n) is \fIunable\fP
to cope elegantly with files which contain the NUL character.
.PP
The \fIfcomp\fP(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.
.PP
The \fIfmerge\fP(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.
.PP
The \fIfhist\fP(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 \fB\-BINary\fP for files which
absolutely must contain NUL characters.
.lf 304 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/z_exit.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008 Peter Miller
.\"
.\"     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/>.
.\"
.br
.ne 1i
.SH EXIT STATUS
The
.I \*(n)
program will exit with a status of 1 on any error.
The
.I \*(n)
program will only exit with a status of 0 if there are no errors.
.lf 305 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/z_ref.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.br
.ne 1i
.SH REFERENCES
This program is based on the algorithm in
.RS
.IR "An O(ND) Difference Algorithm and Its Variations" ,
Eugene W. Myers,
TR 85\[hy]6, 10\[hy]April\[hy]1985,
Department of Computer Science,
The University of Arizona,
Tuscon, Arizona 85721.
.RE
See also:
.RS
.IR "A File Comparison Program" ,
Webb Miller and Eugene W. Myers,
Software Practice and Experience,
Volume 15, No. 11, November 1985.
.RE
.lf 306 ./lib/en/man1/fmerge.1
.lf 1 lib/en/man1/z_cr.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1995, 1998, 2000, 2008, 2009 Peter Miller
.\"
.\"     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/>.
.\"
.br
.ne 2i
.SH COPYRIGHT
.lf 1 etc/version.so
.ds V) 1.18.D001
.ds v) 1.18
.ds Y) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
.lf 23 lib/en/man1/z_cr.so
.if t .ds C) \(co
.if n .ds C) (C)
\*(n) version \*(V)
.br
Copyright \*(C)
.nr d) \n(.d
\*(Y) Peter Miller;
.if '\n(d)'\n(.d' .br
.PP
This program is derived from a work
.br
Copyright \*(C) 1990 David I. Bell.
.PP
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.
.PP
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.
.PP
You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.
.br
.ne 1i
.SH AUTHORS
.TS
tab(;);
l r l.
Peter Miller;Web:;http://miller.emu.id.au/pmiller/
/\e/\e*;E\[hy]Mail:;pmiller@opensource.org.au
.sp
David I. Bell;Web:;http://www.canb.auug.org.au/~dbell
;E\[hy]Mail:;dbell@canb.auug.org.au
.TE
.lf 307 ./lib/en/man1/fmerge.1