DragonFly On-Line Manual Pages
ETCMERGE(1) DragonFly General Commands Manual ETCMERGE(1)
NAME
etcmerge - 3-way merge of /etc with updates from /usr/src
SYNOPSIS
etcmerge 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
difference 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
information 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
directory, 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 conflict markers ("<<<<<<<<", "=====" and ">>>>>>>") indicating
where the conflict is. See merge(1) for details. The files with this
kind of conflict 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
handling 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
differently, 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
directories 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
permissions 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."
REFERENCES
mergemaster(8), merge(1).
AUTHOR
Eivind Eklund <eivind@FreeBSD.org>
July 5, 2003