usr.sbin/mergemaster/mergemaster.8

   1 .\" Copyright (c) 1998-2003 Douglas Barton
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 4, 2006
  28 .Dt MERGEMASTER 8
  29 .Os
  30 .Sh NAME
  31 .Nm mergemaster
  32 .Nd merge configuration files, et al during an upgrade
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl scrvahipCPU
  36 .Op Fl m Ar /path/to/sources
  37 .Op Fl t Ar /path/to/temp/root
  38 .Op Fl d
  39 .Op Fl u Ar N
  40 .Op Fl w Ar N
  41 .Op Fl A Ar architecture
  42 .Op Fl D Ar /path
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility is a Bourne shell script which is designed to aid you
  47 in updating the various configuration and other files
  48 associated with
  49 .Fx .
  50 It is
  51 .Sy HIGHLY
  52 recommended that you back up your
  53 .Pa /etc
  54 directory before beginning this process.
  55 .Pp
  56 The script uses
  57 .Pa /usr/src/etc/Makefile
  58 to build a temporary root environment from
  59 .Pa /
  60 down, populating that environment with the various
  61 files.
  62 You can specify a different source directory
  63 with the
  64 .Op Fl m
  65 command line option, or specify the destination
  66 directory with the
  67 .Op Fl D
  68 option.
  69 It then compares each file in that environment
  70 to its installed counterpart.
  71 When the script finds a
  72 change in the new file, or there is no installed
  73 version of the new file it gives you four options to
  74 deal with it.
  75 You can install the new file as is,
  76 delete the new file, merge the old and new
  77 files (as appropriate) using
  78 .Xr sdiff 1
  79 or leave the file in the temporary root environment to
  80 merge by hand later.
  81 .Pp
  82 By default it creates the temporary root in
  83 .Pa /var/tmp/temproot
  84 and compares the
  85 .Xr cvs 1
  86 version $Id/$FreeBSD strings for files that have them, deleting
  87 the temporary file if the strings match.
  88 If there is
  89 no $Id string, or if the strings are different it
  90 compares the files themselves.
  91 You can
  92 also specify that the script ignore the $Id strings and
  93 compare every file.
  94 .Pp
  95 The merge menu option is designed to let you easily combine your
  96 customizations from the old version of a file into the new one.
  97 While you can use the merge function to incorporate changes from
  98 files that you have not customized,
  99 it is not recommended.
 100 .Pp
 101 The
 102 .Nm
 103 utility checks your umask and issues a warning for anything
 104 other than 022.
 105 While it is not mandatory to grant
 106 world read permissions for most configuration files, you
 107 may run into problems without them.
 108 If you choose a
 109 umask other than 022 and experience trouble later this
 110 could be the cause.
 111 .Pa /etc/master.passwd
 112 is treated as a special case.
 113 If you choose to install
 114 this file or a merged version of it the file permissions
 115 are always 600 (rw-------) for security reasons.
 116 After
 117 installing an updated version of this file you should
 118 probably run
 119 .Xr pwd_mkdb 8
 120 with the -p option to rebuild your password databases
 121 and recreate
 122 .Pa /etc/passwd .
 123 .Pp
 124 The script uses the owner and group id's
 125 that the files are created with by
 126 .Pa /usr/src/etc/Makefile ,
 127 and file permissions as specified by the umask.
 128 Unified diffs are used by default to display any
 129 differences unless you choose context diffs.
 130 .Pp
 131 The
 132 .Nm
 133 utility will source scripts that you specify right before
 134 it starts the comparison, and after it is done running.
 135 The easiest way to handle this is to place the path
 136 to the script(s) in the appropriate variables in your
 137 .Pa .mergemasterrc
 138 file.
 139 The script sourced before comparison is named in
 140 .Ev MM_PRE_COMPARE_SCRIPT ,
 141 and the one sourced after the script is done is
 142 .Ev MM_EXIT_SCRIPT .
 143 This is the recommended way to specify local modifications,
 144 or files that you want to give special handling to.
 145 This includes files that you want to be deleted without
 146 being compared.
 147 Because the named scripts are sourced from within
 148 .Nm ,
 149 all of the script's variables are available for use in
 150 your custom script.
 151 You can also use
 152 .Pa /etc/mergemaster.rc
 153 which will be read before
 154 .Pa .mergemasterrc .
 155 Options specified on the command line are updated last,
 156 and therefore can override both files.
 157 .Pp
 158 The options are as follows:
 159 .Bl -tag -width Fl
 160 .It Fl s
 161 Perform a strict comparison, diff'ing every pair of files.
 162 This comparison is performed line by line,
 163 without regard to CVS $Id's.
 164 .It Fl c
 165 Use context diffs instead of unified diffs.
 166 .It Fl r
 167 Re-run
 168 .Nm
 169 on a previously cleaned directory, skipping the creation of
 170 the temporary root environment.
 171 This option is compatible
 172 with all other options.
 173 .It Fl v
 174 Be more verbose about the process.
 175 You should probably use
 176 this option the first time you run
 177 .Nm .
 178 This option also gives you a list of files that exist
 179 only in the installed version of
 180 .Pa /etc .
 181 .It Fl a
 182 Run automatically.
 183 This option will leave all the files that
 184 differ from the installed versions in the temporary directory
 185 to be dealt with by hand.
 186 If the
 187 .Pa temproot
 188 directory exists, it creates a new one in a previously
 189 non-existent directory.
 190 This option unsets the verbose flag,
 191 but is compatible with all other options.
 192 Setting -a makes
 193 -w superfluous.
 194 .It Fl h
 195 Display usage and help information.
 196 .It Fl i
 197 Automatically install any files that do not exist in the
 198 destination directory.
 199 .It Fl p
 200 Pre-buildworld mode.
 201 Compares only files known to be essential to the success of
 202 {build|install}world,
 203 including
 204 .Pa /etc/make.conf .
 205 .It Fl C
 206 After a standard
 207 .Nm
 208 run,
 209 compares your rc.conf[.local] options to the defaults.
 210 .It Fl P
 211 Preserve files that you replace in
 212 .Pa /var/tmp/mergemaster/preserved-files-<date> ,
 213 or another directory you specify in your
 214 .Nm
 215 rc file.
 216 .It Fl m Ar /path/to/sources
 217 Specify the path to the directory where you want to do the
 218 .Xr make 1 .
 219 (In other words, where your sources are, but -s was already
 220 taken.)
 221 .It Fl t Ar /path/to/temp/root
 222 Create the temporary root environment in
 223 .Pa /path/to/temp/root
 224 instead of the default
 225 .Pa /var/tmp/temproot .
 226 .It Fl d
 227 Add the date and time to the name of the temporary
 228 root directory.
 229 If -t is specified, this option must
 230 follow it if you want the date added too.
 231 .It Fl u Ar N
 232 Specify a numeric umask.
 233 The default is 022.
 234 .It Fl w Ar N
 235 Supply an alternate screen width to the
 236 .Xr sdiff 1
 237 command in numbers of columns.
 238 The default is 80.
 239 .It Fl A Ar architecture
 240 Specify an alternative
 241 .Ev TARGET_ARCH
 242 architecture name.
 243 .It Fl D Ar /path
 244 Specify the destination directory for the installed files.
 245 .It Fl U
 246 Attempt to auto upgrade files that have not been user modified.
 247 .El
 248 .Sh ENVIRONMENT
 249 The
 250 .Nm
 251 utility uses the
 252 .Ev PAGER
 253 environment variable if set.
 254 Otherwise it uses
 255 .Xr more 1 .
 256 If
 257 .Ev PAGER
 258 specifies a program outside
 259 its
 260 limited
 261 .Ev PATH
 262 without specifying the full path,
 263 .Nm
 264 prompts you with options on how to proceed.
 265 The
 266 .Ev MM_PRE_COMPARE_SCRIPT
 267 and
 268 .Ev MM_EXIT_SCRIPT
 269 variables are used as described above.
 270 Other variables that are used by the script internally
 271 can be specified in
 272 .Pa .mergemasterrc
 273 as described in more detail below.
 274 .Sh FILES
 275 .Bl -tag -width $HOME/.mergemasterrc -compact
 276 .It Pa /etc/mergemaster.rc
 277 .It Pa $HOME/.mergemasterrc
 278 .El
 279 .Pp
 280 The
 281 .Nm
 282 utility will
 283 .Ic .\&
 284 (source) these files if they exist.
 285 Command line options
 286 will override rc file options.
 287 .Pa $HOME/.mergemasterrc
 288 overrides
 289 .Pa /etc/mergemaster.rc .
 290 Here is an example
 291 with all values commented out:
 292 .Pp
 293 .Bd -literal
 294 # These are options for mergemaster, with their default values listed
 295 # The following options have command line overrides
 296 #
 297 # Directory to install the temporary root environment into
 298 #TEMPROOT='/var/tmp/temproot'
 299 #
 300 # Strict comparison bypasses the CVS $Id tests and compares every file
 301 #STRICT=no
 302 #
 303 # Type of diff, such as unified, context, etc.
 304 #DIFF_FLAG='-u'
 305 #
 306 # Additional options for diff.  This will get unset when using -s.
 307 #DIFF_OPTIONS='-I$\&FreeBSD:.*[$]'      # Ignores CVS Id tags
 308 #
 309 # Verbose mode includes more details and additional checks
 310 #VERBOSE=
 311 #
 312 # Automatically install files that do not exist on the system already
 313 #AUTO_INSTALL=
 314 #
 315 # Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf
 316 #COMP_CONFS=yes
 317 #
 318 # Preserve files that you replace
 319 #PRESERVE_FILES=yes
 320 #PRESERVE_FILES_DIR=/var/tmp/mergemaster/preserved-files-`date +%y%m%d-%H%M%S`
 321 #
 322 # Sourcedir is the directory to do the 'make' in (where the new files are)
 323 #SOURCEDIR='/usr/src/etc'
 324 #
 325 # The umask for mergemaster to compare the default file's modes to
 326 #NEW_UMASK=022
 327 #
 328 # Specify the destination directory for the installed files
 329 #DESTDIR=
 330 #
 331 # The following options have no command line overrides
 332 # For those who just cannot stand including the full path to PAGER
 333 #DONT_CHECK_PAGER=
 334 #
 335 # If you set 'yes' above, make sure to include the PATH to your pager
 336 #PATH=/bin:/usr/bin:/usr/sbin
 337 #
 338 # Don't compare the old and new motd files
 339 #IGNORE_MOTD=yes
 340 #
 341 # Specify the path to scripts to run before the comparison starts,
 342 # and/or after the script has finished its work
 343 #MM_PRE_COMPARE_SCRIPT=
 344 #MM_EXIT_SCRIPT=
 345 .Ed
 346 .Sh EXIT STATUS
 347 Exit status is 0 on successful completion, or if the user bails out
 348 manually at some point during execution.
 349 .Pp
 350 Exit status is 1 if it fails for one of the following reasons:
 351 .Pp
 352 Invalid command line option
 353 .Pp
 354 Failure to create the temporary root environment
 355 .Pp
 356 Failure to populate the temporary root
 357 .Sh EXAMPLES
 358 Typically all you will need to do is type
 359 .Nm
 360 at the prompt and the script will do all the work for you.
 361 .Pp
 362 To use context diff's and have
 363 .Nm
 364 explain more things as it goes along, use:
 365 .Pp
 366 .Dl # mergemaster -cv
 367 .Pp
 368 To specify that
 369 .Nm
 370 put the temporary root environment in
 371 .Pa /usr/tmp/root ,
 372 use:
 373 .Pp
 374 .Dl # mergemaster -t /usr/tmp/root
 375 .Pp
 376 To specify a 110 column screen with a strict
 377 comparison, use:
 378 .Pp
 379 .Dl # mergemaster -sw 110
 380 .Sh SEE ALSO
 381 .Xr cvs 1 ,
 382 .Xr diff 1 ,
 383 .Xr make 1 ,
 384 .Xr more 1 ,
 385 .Xr sdiff 1 ,
 386 .Xr pwd_mkdb 8
 387 .Pp
 388 .Pa /usr/src/etc/Makefile
 389 .Rs
 390 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
 391 .%T The Cutting Edge (using make world)
 392 .%A Nik Clayton
 393 .Re
 394 .Sh HISTORY
 395 The
 396 .Nm
 397 utility was first publicly available on one of my
 398 web pages in a much simpler form under the name
 399 .Pa comproot
 400 on 13 March 1998.
 401 The idea for creating the
 402 temporary root environment comes from Nik Clayton's
 403 make world tutorial which is referenced above.
 404 .Sh AUTHORS
 405 This manual page and the script itself were written by
 406 .An Douglas Barton Aq DougB@FreeBSD.org .
 407 .Sh BUGS
 408 There are no known bugs.
 409 Please report any problems,
 410 comments or suggestions to the author.
 411 Several of the
 412 improvements to this program have come from user
 413 suggestions.
 414 Thank you.