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