ETCMERGE(1) BSD General Commands Manual ETCMERGE(1)NAMEetcmerge — 3-way merge of /etc with updates from /usr/src
SYNOPSISetcmerge init
etcmerge install
DESCRIPTION
WARNING: ETCMERGE HAS NOT UNDERGONE EXTENSIVE PRODUCTION USE, SO USE AT
YOUR OWN RISK. Taking a backup of /etc before running it won't hurt.
etcmerge is a tool for keeping your /etc up to date as you update your
system. It fills the same niche as mergemaster(8), with the primary dif‐
ference being that etcmerge requires much less manual work. This is
because etcmerge merges two sets of changes instead of two copies of etc:
The changes you have done locally are merged with the changes done by
FreeBSD. etcmerge does this by tracking three instead of two copies of
etc - the active /etc (the one you are running your system on), the new
etc distributed from FreeBSD (generated from /usr/src by etcmerge ), and
a reference copy of the etc that was originally distributed from FreeBSD
and which you have changed to get the active /etc.
The use of all three copies allow etcmerge to find the two sets of
changes - changes by you (the difference from reference to installed etc)
and changes by FreeBSD (the difference from reference etc to new etc).
A three way merge is usually fully automated - no user interaction is
needed for the merge itself. However, sometimes conflicting changes have
been made - you have done one change, and FreeBSD has done a different
change to the same part of /etc.
ROUGH DESCRIPTION OF USE
First, ensure you have a copy of the /etc distributed by FreeBSD (BEFORE
you or sysinstall(8) started modifying it) stored in /var/db/etc. There
are two easy ways to do this:
1. Download a copy matching your installation from
http://people.freebsd.org/~eivind/etc/ and extract this in /var/db/.
2. Run mergemaster(8) one last time to get your /etc up to date. Then
rerun mergemaster(8) with the -v option, exit after it creates
/var/tmp/temproot, and copy /var/tmp/temproot/etc to /var/db/etc.
When you have /var/db/etc initialized, start a merge with etcmerge init
(as root). etcmerge will run for a while, and start printing out infor‐
mation about what operations it does, prefixed with ETCMERGE:. When it
is finished, it will print out a line saying which work directory it has
worked in (by default, ${HOME}/etc-work/<date>). Change to this direc‐
tory, and check if you have any .conflicts files there. If you do, check
through them, and resolve the conflicts. The conflicts will be recorded
in different ways depending on what kind of conflicts they are. Under
the directory etc-merged you'll find a replacement for /etc, including
both changes done by you and FreeBSD. Any files that have normal change
conflicts (you and FreeBSD have made different changes) will have con‐
flict markers ("<<<<<<<<", "=====" and ">>>>>>>") indicating where the
conflict is. See merge(1) for details. The files with this kind of con‐
flict will be listed in 7.conflicts. Other forms of conflicts will be
listed in other .conflict files; see below for details if you get any of
these.
When you are finished with resolving conflicts, type etcmerge install to
make the present etc-merged directory replace /etc, and make etc-new
(newly generated etc, based on the present /usr/src) the new reference
etc.
INTERNAL DESCRIPTION
In order to do its work, etcmerge divides the files it operate in into
different classes, and do different operations depending on which class
the files belong in. This division makes a difference for how each file
is treated. The exact treatment of each class will be printed out by
etcmerge when you run it, along with how many files is in each class, and
how many conflicts occur. Each conflict is registered in
<class-number>.conflicts - e.g. 7.conflicts for conflicts in class 7
(3-way merged files).
CLASSES
The following table define what the class numbers refer to. The headings
"Reference", "New", and "Active" refers to various copies of etc - the
one generated from /usr/src (New), the one stored as a Reference copy
(basically the one generated from /usr/src the last time you ran etcmerge
or the one distributed with the FreeBSD you installed), and the one
presently Active (ie, the one stored in /etc when you run etcmerge ).
Class Reference New Active
1 Absent Absent Present
2 Absent Present Absent
3 Absent Present Present
4 Present Absent Absent
5 Present Absent Present
6 Present Present Absent
7 Present Present Present
Depending on what class each file (and I'm talking flat files here) is
in, it will be handled differently. (See separate description for han‐
dling of directories and special files.) The following table describes
how each class of files are handled when there are no conflicts in the
file.
Class File merge handling
1 Copy from Active
2 Copy from New
3 Copy from New
4 Drop file
5 Drop file (store in conflict dir if diffs)
6 Drop file (store in conflict dir)
7 Do a 3-way merge between all variant, and store result in
etc-merged
Depending on what class a file is in, conflicts will be detected differ‐
ently, and handled differently. The below table detail how conflicts are
detected and handled for each class.
Class File conflict handling
1 Cannot be a conflict
2 Cannot be a conflict
3 If there are differences between New and Active, store a
diff file in merged-
changed.
4 Cannot be a conflict
5 If there are differences between New and Active, store a
diff file in merged-
removed.
6 Store file in merged-conflicts, with a diff file if there
are diffs between
Reference and New
7 Conflicts are indicated inside the file, using <<<<<<<<<,
======= and >>>>>>>>>
as markers. See
merge(1).
Directories and special files are also handled by etcmerge. Empty direc‐
tories and special files are handled by class (see the tables below).
Directories with content is handled alongside files. When a file is
copied over to the merged etc (the one etcmerge generates), all prefix
directories will be copied too, using permissions either from the active
(if available) or the new etc. Ie, if etcmerge decide to copy
etc/ssh/ssh_config from /etc, then merged-etc/ssh will get the same per‐
missions as /etc/ssh.
This table details how special files (symlinks, device nodes, pipes, etc)
and empty directories are handled. etcmerge does not look for conflicts
for these, but just copies them as appropriate.
Class Directory/special file handling
1 Copy from Active
2 Copy from New
3 Copy from Active
4 Ignore dir/special file
5 Ignore dir/special file
6 Ignore dir/special file
7 Copy from Active
DIRECTORIES USED
etc-merged Merged etc directory, based on etc-new but customized
with on your changes.
etc-new New etc directory, as distributed by FreeBSD. Created
based on /usr/src.
classes Data about what goes in what class
merged-removed Files that have been removed, along
with .diff files if the active file was
different from the reference file.
merged-changed Files that have been replaced by the
update, along with .diff files saying
what changes this has resulted in.
merged-conflicts Files that are present in new and
reference, but not in the active etc.
If these are changed, a .diff is also
stored here."
REFERENCESmergemaster(8), merge(1).
AUTHOR
Eivind Eklund <eivind@FreeBSD.org>
July 5, 2003
