1 .\" Copyright (c) 1998-2002 Douglas Barton
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd merge configuration files, et al during an upgrade
36 .Op Fl m Ar /path/to/sources
37 .Op Fl t Ar /path/to/temp/root
44 is a Bourne shell script which is designed to aid you
45 in updating the various configuration and other files
50 recommended that you back up your
52 directory before beginning this process.
55 .Pa /usr/src/etc/Makefile
56 to build a temporary root environment from
58 down, populating that environment with the various
60 You can specify a different source directory
63 command line option, or specify the destination
67 It then compares each file in that environment
68 to its installed counterpart.
69 When the script finds a
70 change in the new file, or there is no installed
71 version of the new file it gives you four options to
73 You can install the new file as is,
74 delete the new file, merge the old and new
75 files (as appropriate) using
77 or leave the file in the temporary root environment to
80 By default it creates the temporary root in
84 version $Id/$FreeBSD strings for files that have them, deleting
85 the temporary file if the strings match.
87 no $Id string, or if the strings are different it
88 compares the files themselves.
90 also specify that the script ignore the $Id strings and
94 checks your umask and issues a warning for anything
95 other than 022. While it is not mandatory to grant
96 world read permissions for most configuration files, you
97 may run into problems without them.
99 umask other than 022 and experience trouble later this
101 .Pa /etc/master.passwd
102 is treated as a special case.
103 If you choose to install
104 this file or a merged version of it the file permissions
105 are always 600 (rw-------) for security reasons.
107 installing an updated version of this file you should
110 with the -p option to rebuild your password databases
114 The script uses the owner and group id's
115 that the files are created with by
116 .Pa /usr/src/etc/Makefile ,
117 and file permissions as specified by the umask.
118 Unified diffs are used by default to display any
119 differences unless you choose context diffs.
122 will source scripts that you specify right before
123 it starts the comparison, and after it's done running.
124 The easiest way to handle this is to place the path
125 to the script(s) in the appropriate variables in your
128 The script sourced before comparison is named in
129 .Ev MM_PRE_COMPARE_SCRIPT ,
130 and the one sourced after the script is done is
132 This is the recommended way to specify local modifications,
133 or files that you want to give special handling to.
134 This includes files that you want to be deleted without
136 Because the named scripts are sourced from within
138 all of the script's variables are available for use in
141 .Pa /etc/mergemaster.rc
142 which will be read before
144 Options specified on the command line are updated last,
145 and therefore can override both files.
147 The options are as follows:
150 Perform a strict comparison, diff'ing every pair of files.
151 This comparison is performed line by line,
152 without regard to CVS $Id's.
154 Use context diffs instead of unified diffs.
158 on a previously cleaned directory, skipping the creation of
159 the temporary root environment.
160 This option is compatible
161 with all other options.
163 Be more verbose about the process.
164 You should probably use
165 this option the first time you run
167 This option also gives you a list of files that exist
168 only in the installed version of
172 This option will leave all the files that
173 differ from the installed versions in the temporary directory
174 to be dealt with by hand.
177 directory exists, it creates a new one in a previously
178 non-existent directory.
179 This option unsets the verbose flag,
180 but is compatible with all other options.
184 Display usage and help information.
186 Automatically install any files that do not exist in the
187 destination directory.
190 Compares only files known to be essential to the success of
191 {build|install}world,
198 compares your rc.conf[.local] options to the defaults.
199 .It Fl m Ar /path/to/sources
200 Specify the path to the directory where you want to do the
202 (In other words, where your sources are, but -s was already
204 .It Fl t Ar /path/to/temp/root
205 Create the temporary root environment in
206 .Pa /path/to/temp/root
207 instead of the default
208 .Pa /var/tmp/temproot .
210 Add the date and time to the name of the temporary
212 If -t is specified, this option must
213 follow it if you want the date added too.
215 Specify a numeric umask.
218 Supply an alternate screen width to the
220 command in numbers of columns.
223 Specify the destination directory for the installed files.
230 environment variable if set.
235 specifies a program outside
239 without specifying the full path,
241 prompts you with options on how to proceed.
243 .Ev MM_PRE_COMPARE_SCRIPT
246 variables are used as described above.
247 Other variables that are used by the script internally
250 as described in more detail below.
252 Typically all you will need to do is type
254 at the prompt and the script will do all the work for you.
256 To use context diff's and have
258 explain more things as it goes along, use:
260 .Dl # mergemaster -cv
264 put the temporary root environment in
268 .Dl # mergemaster -t /usr/tmp/root
270 To specify a 110 column screen with a strict
273 .Dl # mergemaster -sw 110
275 .Bl -tag -width $HOME/.mergemasterrc -compact
276 .It Pa /etc/mergemaster.rc
277 .It Pa $HOME/.mergemasterrc
281 will . (source) these files if they exist.
283 will override rc file options.
284 .Pa $HOME/.mergemasterrc
286 .Pa /etc/mergemaster.rc .
288 with all values commented out:
291 # These are options for mergemaster, with their default values listed
292 # The following options have command line overrides
294 # Directory to install the temporary root environment into
295 #TEMPROOT='/var/tmp/temproot'
297 # Strict comparison bypasses the CVS $Id tests and compares every file
300 # Flag(s) to use for diff displayed when files differ
303 # Verbose mode includes more details and additional checks
306 # Automatically install files that do not exist on the system already
309 # Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf
312 # Sourcedir is the directory to do the 'make' in (where the new files are)
313 #SOURCEDIR='/usr/src/etc'
315 # The umask for mergemaster to compare the default file's modes to
318 # Specify the destination directory for the installed files
321 # The following options have no command line overrides
322 # For those who just cannot stand including the full path to PAGER
325 # If you set 'yes' above, make sure to include the PATH to your pager
326 #PATH=/bin:/usr/bin:/usr/sbin
328 # Don't compare the old and new motd files
331 # Specify the path to scripts to run before the comparison starts,
332 # and/or after the script has finished its work
333 #MM_PRE_COMPARE_SCRIPT=
344 .Pa /usr/src/etc/Makefile
346 .%O http://www.FreeBSD.org/handbook/makeworld.html
347 .%T The Cutting Edge (using make world)
351 Exit status is 0 on successful completion, or if the user bails out
352 manually at some point during execution.
354 Exit status is 1 if it fails for one of the following reasons:
356 Invalid command line option
358 Failure to create the temporary root environment
360 Failure to populate the temporary root
364 script was first publicly available on one of my
365 web pages in a much simpler form under the name
367 on 13 March 1998. The idea for creating the
368 temporary root environment comes from Nik Clayton's
369 make world tutorial which is referenced above.
371 This manual page and the script itself were written by
372 .An Douglas Barton Aq DougB@FreeBSD.org .
374 There are no known bugs.
375 Please report any problems,
376 comments or suggestions to the author.
378 improvements to this program have come from user