usr.sbin/etcupdate/etcupdate.8

   1 .\" Copyright (c) 2010-2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd August 9, 2022
  27 .Dt ETCUPDATE 8
  28 .Os
  29 .Sh NAME
  30 .Nm etcupdate
  31 .Nd "manage updates to system files not updated by installworld"
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl npBFN
  35 .Op Fl d Ar workdir
  36 .Op Fl r | Fl s Ar source | Fl t Ar tarball
  37 .Op Fl A Ar patterns
  38 .Op Fl D Ar destdir
  39 .Op Fl I Ar patterns
  40 .Op Fl L Ar logfile
  41 .Op Fl M Ar options
  42 .Op Fl m Ar make
  43 .Nm
  44 .Cm build
  45 .Op Fl BN
  46 .Op Fl d Ar workdir
  47 .Op Fl s Ar source
  48 .Op Fl L Ar logfile
  49 .Op Fl M Ar options
  50 .Op Fl m Ar make
  51 .Ar tarball
  52 .Nm
  53 .Cm diff
  54 .Op Fl d Ar workdir
  55 .Op Fl D Ar destdir
  56 .Op Fl I Ar patterns
  57 .Op Fl L Ar logfile
  58 .Nm
  59 .Cm extract
  60 .Op Fl BN
  61 .Op Fl d Ar workdir
  62 .Op Fl s Ar source | Fl t Ar tarball
  63 .Op Fl D Ar destdir
  64 .Op Fl L Ar logfile
  65 .Op Fl M Ar options
  66 .Op Fl m Ar make
  67 .Nm
  68 .Cm resolve
  69 .Op Fl p
  70 .Op Fl d Ar workdir
  71 .Op Fl D Ar destdir
  72 .Op Fl L Ar logfile
  73 .Nm
  74 .Cm revert
  75 .Op Fl d Ar workdir
  76 .Op Fl D Ar destdir
  77 .Op Fl L Ar logfile
  78 .Ar
  79 .Nm
  80 .Cm status
  81 .Op Fl d Ar workdir
  82 .Op Fl D Ar destdir
  83 .Sh DESCRIPTION
  84 The
  85 .Nm
  86 utility is a tool for managing updates to files that are not updated as
  87 part of
  88 .Sq make installworld
  89 such as files in
  90 .Pa /etc .
  91 It manages updates by doing a three-way merge of changes made to these
  92 files against the local versions.
  93 It is also designed to minimize the amount of user intervention with
  94 the goal of simplifying upgrades for clusters of machines.
  95 .Pp
  96 To perform a three-way merge,
  97 .Nm
  98 keeps copies of the current and previous versions of files that it manages.
  99 These copies are stored in two trees known as the
 100 .Dq current
 101 and
 102 .Dq previous
 103 trees.
 104 During a merge,
 105 .Nm
 106 compares the
 107 .Dq current
 108 and
 109 .Dq previous
 110 copies of each file to determine which changes need to be merged into the
 111 local version of each file.
 112 If a file can be updated without generating a conflict,
 113 .Nm
 114 will update the file automatically.
 115 If the local changes to a file conflict with the changes made to a file in
 116 the source tree,
 117 then a merge conflict is generated.
 118 The conflict must be resolved after the merge has finished.
 119 The
 120 .Nm
 121 utility will not perform a new merge until all conflicts from an earlier
 122 merge are resolved.
 123 .Sh MODES
 124 The
 125 .Nm
 126 utility supports several modes of operation.
 127 The mode is specified via an optional command argument.
 128 If present, the command must be the first argument on the command line.
 129 If a command is not specified, the default mode is used.
 130 .Ss Default Mode
 131 The default mode merges changes from the source tree to the destination
 132 directory.
 133 First,
 134 it updates the
 135 .Dq current
 136 and
 137 .Dq previous
 138 trees.
 139 Next,
 140 it compares the two trees merging changes into the destination directory.
 141 Finally,
 142 it displays warnings for any conditions it could not handle automatically.
 143 .Pp
 144 If the
 145 .Fl r
 146 option is not specified,
 147 then the first step taken is to update the
 148 .Dq current
 149 and
 150 .Dq previous
 151 trees.
 152 If a
 153 .Dq current
 154 tree already exists,
 155 then that tree is saved as the
 156 .Dq previous
 157 tree.
 158 An older
 159 .Dq previous
 160 tree is removed if it exists.
 161 By default the new
 162 .Dq current
 163 tree is built from a source tree.
 164 However,
 165 if a tarball is specified via the
 166 .Fl t
 167 option,
 168 then the tree is extracted from that tarball instead.
 169 .Pp
 170 Next,
 171 .Nm
 172 compares the files in the
 173 .Dq current
 174 and
 175 .Dq previous
 176 trees.
 177 If a file was removed from the
 178 .Dq current
 179 tree,
 180 then it will be removed from the destination directory only if it
 181 does not have any local modifications.
 182 If a file was added to the
 183 .Dq current
 184 tree,
 185 then it will be copied to the destination directory only if it
 186 would not clobber an existing file.
 187 If a file is changed in the
 188 .Dq current
 189 tree,
 190 then
 191 .Nm
 192 will attempt to merge the changes into the version of the file in the
 193 destination directory.
 194 If the merge encounters conflicts,
 195 then a version of the file with conflict markers will be saved for
 196 future resolution.
 197 If the merge does not encounter conflicts,
 198 then the merged version of the file will be saved in the destination
 199 directory.
 200 If
 201 .Nm
 202 is not able to safely merge in changes to a file other than a merge conflict,
 203 it will generate a warning.
 204 .Pp
 205 For each file that is updated a line will be output with a leading character
 206 to indicate the action taken.
 207 The possible actions follow:
 208 .Pp
 209 .Bl -tag -width "A" -compact -offset indent
 210 .It A
 211 Added
 212 .It C
 213 Conflict
 214 .It D
 215 Deleted
 216 .It M
 217 Merged
 218 .It U
 219 Updated
 220 .El
 221 .Pp
 222 Finally,
 223 if any warnings were encountered they are displayed after the merge has
 224 completed.
 225 .Pp
 226 Note that for certain files
 227 .Nm
 228 will perform post-install actions any time that the file is updated.
 229 Specifically,
 230 .Xr pwd_mkdb 8
 231 is invoked if
 232 .Pa /etc/master.passwd
 233 is changed,
 234 .Xr cap_mkdb 1
 235 is invoked to update
 236 .Pa /etc/login.conf.db
 237 if
 238 .Pa /etc/login.conf
 239 is changed,
 240 .Xr newaliases 1
 241 is invoked if
 242 .Pa /etc/mail/aliases
 243 is changed,
 244 .Xr services_mkdb 8
 245 is invoked if
 246 .Pa /etc/services
 247 is changed,
 248 .Xr tzsetup 8
 249 is invoked if
 250 .Pa /etc/localtime
 251 is changed and if
 252 .Fa /var/db/zoneinfo
 253 exists,
 254 and
 255 .Pa /etc/rc.d/motd
 256 is invoked if
 257 .Pa /etc/motd
 258 is changed.
 259 One exception is that if
 260 .Pa /etc/mail/aliases
 261 is changed and the destination directory is not the default,
 262 then a warning will be issued instead.
 263 This is due to a limitation of the
 264 .Xr newaliases 1
 265 command.
 266 Similarly,
 267 if
 268 .Pa /etc/motd
 269 is changed and the destination directory is not the default,
 270 then
 271 .Pa /etc/rc.d/motd
 272 will not be executed due to a limitation of that script.
 273 In this case no warning is issued as the result of
 274 .Pa /etc/rc.d/motd
 275 is merely cosmetic and will be corrected on the next reboot.
 276 .Ss Build Mode
 277 The
 278 .Cm build
 279 mode is used to build a tarball that contains a snapshot of a
 280 .Dq current
 281 tree.
 282 This tarball can be used by the default and extract modes.
 283 Using a tarball can allow
 284 .Nm
 285 to perform a merge without requiring a source tree that matches the
 286 currently installed world.
 287 The
 288 .Fa tarball
 289 argument specifies the name of the file to create.
 290 The file will be a
 291 .Xr tar 5
 292 file compressed with
 293 .Xr bzip2 1 .
 294 .Ss Diff Mode
 295 The
 296 .Cm diff
 297 mode compares the versions of files in the destination directory to the
 298 .Dq current
 299 tree and generates a unified format diff of the changes.
 300 This can be used to determine which files have been locally modified and how.
 301 Note that
 302 .Nm
 303 does not manage files that are not maintained in the source tree such as
 304 .Pa /etc/fstab
 305 and
 306 .Pa /etc/rc.conf .
 307 .Ss Extract Mode
 308 The
 309 .Cm extract
 310 mode generates a new
 311 .Dq current
 312 tree.
 313 Unlike the default mode,
 314 it does not save any existing
 315 .Dq current
 316 tree and does not modify any existing
 317 .Dq previous
 318 tree.
 319 The new
 320 .Dq current
 321 tree can either be built from a source tree or extracted from a tarball.
 322 .Ss Resolve Mode
 323 The
 324 .Cm resolve
 325 mode is used to resolve any conflicts encountered during a merge.
 326 In this mode,
 327 .Nm
 328 iterates over any existing conflicts prompting the user for actions to take
 329 on each conflicted file.
 330 For each file, the following actions are available:
 331 .Pp
 332 .Bl -tag -width "(tf) theirs-full" -compact
 333 .It (p)  postpone
 334 Ignore this conflict for now.
 335 .It (df) diff-full
 336 Show all changes made to the merged file as a unified diff.
 337 .It (e)  edit
 338 Change the merged file in an editor.
 339 .It (r)  resolved
 340 Install the merged version of the file into the destination directory.
 341 .It (mf) mine-full
 342 Use the version of the file in the destination directory and ignore any
 343 changes made to the file in the
 344 .Dq current
 345 tree.
 346 .It (tf) theirs-full
 347 Use the version of the file from the
 348 .Dq current
 349 tree and discard any local changes made to the file.
 350 .It (h)  help
 351 Display the list of commands.
 352 .El
 353 .Ss Revert Mode
 354 The
 355 .Cm revert
 356 mode is used to restore the stock versions of files.
 357 In this mode,
 358 .Nm
 359 installs the stock version of requested files.
 360 This mode cannot be used to restore directories, only individual files.
 361 .Ss Status Mode
 362 The
 363 .Cm status
 364 mode shows a summary of the results of the most recent merge.
 365 First it lists any files for which there are unresolved conflicts.
 366 Next it lists any warnings generated during the last merge.
 367 If the last merge did not generate any conflicts or warnings,
 368 then nothing will be output.
 369 .Sh OPTIONS
 370 The following options are available.
 371 Note that most options do not apply to all modes.
 372 .Bl -tag -width ".Fl A Ar patterns"
 373 .It Fl A Ar patterns
 374 Always install the new version of any files that match any of the patterns
 375 listed in
 376 .Ar patterns .
 377 Each pattern is evaluated as an
 378 .Xr sh 1
 379 shell pattern.
 380 This option may be specified multiple times to specify multiple patterns.
 381 Multiple space-separated patterns may also be specified in a single
 382 option.
 383 Note that ignored files specified via the
 384 .Ev IGNORE_FILES
 385 variable or the
 386 .Fl I
 387 option will not be installed.
 388 .It Fl B
 389 Do not build generated files in a private object tree.
 390 Instead,
 391 reuse the generated files from a previously built object tree that matches
 392 the source tree.
 393 This can be useful to avoid gratuitous conflicts in
 394 .Xr sendmail 8
 395 configuration
 396 files when bootstrapping.
 397 It can also be useful for building a tarball that matches a specific
 398 world build.
 399 .It Fl D Ar destdir
 400 Specify an alternate destination directory as the target of a merge.
 401 This is analogous to the
 402 .Dv DESTDIR
 403 variable used with
 404 .Sq make installworld .
 405 The default destination directory is an empty string which results in
 406 merges updating
 407 .Pa /etc
 408 on the local machine.
 409 .It Fl d Ar workdir
 410 Specify an alternate directory to use as the work directory.
 411 The work directory is used to store the
 412 .Dq current
 413 and
 414 .Dq previous
 415 trees as well as unresolved conflicts.
 416 The default work directory is
 417 .Pa <destdir>/var/db/etcupdate .
 418 .It Fl F
 419 Ignore changes in the FreeBSD ID string when comparing files in the
 420 destination directory to files in either of the
 421 .Dq current
 422 or
 423 .Dq previous
 424 trees.
 425 In
 426 .Cm diff
 427 mode,
 428 this reduces noise due to FreeBSD ID string changes in the output.
 429 During an update this can simplify handling for harmless conflicts caused
 430 by FreeBSD ID string changes.
 431 .Pp
 432 Specifically,
 433 if a file in the destination directory is identical to the same file in the
 434 .Dq previous
 435 tree modulo the FreeBSD ID string,
 436 then the file is treated as if it was unmodified and the
 437 .Dq current
 438 version of the file will be installed.
 439 Similarly,
 440 if a file in the destination directory is identical to the same file in the
 441 .Dq current
 442 tree modulo the FreeBSD ID string,
 443 then the
 444 .Dq current
 445 version of the file will be installed to update the ID string.
 446 If the
 447 .Dq previous
 448 and
 449 .Dq current
 450 versions of the file are identical,
 451 then
 452 .Nm
 453 will not change the file in the destination directory.
 454 .Pp
 455 Due to limitations in the
 456 .Xr diff 1
 457 command,
 458 this option may not have an effect if there are other changes in a file that
 459 are close to the FreeBSD ID string.
 460 .It Fl I Ar patterns
 461 Ignore any files that match any of the patterns listed in
 462 .Ar patterns .
 463 No warnings or other messages will be generated for those files during a
 464 merge.
 465 Each pattern is evaluated as an
 466 .Xr sh 1
 467 shell pattern.
 468 This option may be specified multiple times to specify multiple patterns.
 469 Multiple space-separated patterns may also be specified in a single
 470 option.
 471 .It Fl L Ar logfile
 472 Specify an alternate path for the log file.
 473 The
 474 .Nm
 475 utility logs each command that it invokes along with the standard output
 476 and standard error to this file.
 477 By default the log file is stored in a file named
 478 .Pa log
 479 in the work directory.
 480 .It Fl M Ar options
 481 Pass
 482 .Ar options
 483 as additional parameters to
 484 .Xr make 1
 485 when building a
 486 .Dq current
 487 tree.
 488 This can be used for to set the
 489 .Dv TARGET
 490 or
 491 .Dv TARGET_ARCH
 492 variables for a cross-build.
 493 .It Fl m Ar make
 494 Use
 495 .Ar make
 496 as the
 497 .Xr make 1
 498 binary when building a
 499 .Dq current
 500 tree.
 501 .It Fl n
 502 Enable
 503 .Dq dry-run
 504 mode.
 505 Do not merge any changes to the destination directory.
 506 Instead,
 507 report what actions would be taken during a merge.
 508 Note that the existing
 509 .Dq current
 510 and
 511 .Dq previous
 512 trees will not be changed.
 513 If the
 514 .Fl r
 515 option is not specified,
 516 then a temporary
 517 .Dq current
 518 tree will be extracted to perform the comparison.
 519 .It Fl N
 520 Perform a
 521 .Dv NO_ROOT
 522 build when building a
 523 .Dq current
 524 tree.
 525 The resulting tree will include a corresponding
 526 .Pa METALOG
 527 file at its root.
 528 .It Fl p
 529 Enable
 530 .Dq pre-world
 531 mode.
 532 Only merge changes to files that are necessary to successfully run
 533 .Sq make installworld
 534 or
 535 .Sq make installkernel .
 536 When this flag is enabled,
 537 the existing
 538 .Dq current
 539 and
 540 .Dq previous
 541 trees are left alone.
 542 Instead,
 543 a temporary tree is populated with the necessary files.
 544 This temporary tree is compared against the
 545 .Dq current
 546 tree.
 547 This allows a normal update to be run after
 548 .Sq make installworld
 549 has completed.
 550 Any conflicts generated during a
 551 .Dq pre-world
 552 update should be resolved by a
 553 .Dq pre-world
 554 .Cm resolve .
 555 .It Fl r
 556 Do not update the
 557 .Dq current
 558 and
 559 .Dq previous
 560 trees during a merge.
 561 This can be used to
 562 .Dq re-run
 563 a previous merge operation.
 564 .It Fl s Ar source
 565 Specify an alternate source tree to use when building or extracting a
 566 .Dq current
 567 tree.
 568 The default source tree is
 569 .Pa /usr/src .
 570 .It Fl t Ar tarball
 571 Extract a new
 572 .Dq current
 573 tree from a tarball previously generated by the
 574 .Cm build
 575 command rather than building the tree from a source tree.
 576 .El
 577 .Sh CONFIG FILE
 578 The
 579 .Nm
 580 utility can also be configured by setting variables in an optional
 581 configuration file named
 582 .Pa /etc/etcupdate.conf .
 583 Note that command line options override settings in the configuration file.
 584 The configuration file is executed by
 585 .Xr sh 1 ,
 586 so it uses that syntax to set configuration variables.
 587 The following variables can be set:
 588 .Bl -tag -width ".Ev ALWAYS_INSTALL"
 589 .It Ev ALWAYS_INSTALL
 590 Always install files that match any of the patterns listed in this variable
 591 similar to the
 592 .Fl A
 593 option.
 594 .It Ev DESTDIR
 595 Specify an alternate destination directory similar to the
 596 .Fl D
 597 option.
 598 .It Ev EDITOR
 599 Specify a program to edit merge conflicts.
 600 .It Ev FREEBSD_ID
 601 Ignore changes in the FreeBSD ID string similar to the
 602 .Fl F
 603 option.
 604 This is enabled by setting the variable to a non-empty value.
 605 .It Ev IGNORE_FILES
 606 Ignore files that match any of the patterns listed in this variable
 607 similar to the
 608 .Fl I
 609 option.
 610 .It Ev LOGFILE
 611 Specify an alternate path for the log file similar to the
 612 .Fl L
 613 option.
 614 .It Ev MAKE_CMD
 615 Specify the
 616 .Xr make 1
 617 binary when building a
 618 .Dq current
 619 tree similar to the
 620 .Fl m
 621 option.
 622 .It Ev MAKE_OPTIONS
 623 Pass additional options to
 624 .Xr make 1
 625 when building a
 626 .Dq current
 627 tree similar to the
 628 .Fl M
 629 option.
 630 .It Ev SRCDIR
 631 Specify an alternate source tree similar to the
 632 .Fl s
 633 option.
 634 .It Ev WORKDIR
 635 Specify an alternate work directory similar to the
 636 .Fl d
 637 option.
 638 .El
 639 .Sh ENVIRONMENT
 640 The
 641 .Nm
 642 utility uses the program identified in the
 643 .Ev EDITOR
 644 environment variable to edit merge conflicts.
 645 If
 646 .Ev EDITOR
 647 is not set,
 648 .Xr vi 1
 649 is used as the default editor.
 650 .Sh FILES
 651 .Bl -tag -width ".Pa /var/db/etcupdate/log" -compact
 652 .It Pa /etc/etcupdate.conf
 653 Optional config file.
 654 .It Pa /var/db/etcupdate
 655 Default work directory used to store trees and other data.
 656 .It Pa /var/db/etcupdate/log
 657 Default log file.
 658 .El
 659 .Sh EXIT STATUS
 660 .Ex -std
 661 .Sh EXAMPLES
 662 To compare the files in
 663 .Pa /etc
 664 with the stock versions:
 665 .Pp
 666 .Dl "etcupdate diff"
 667 .Pp
 668 To merge changes after an upgrade via the buildworld and installworld process:
 669 .Pp
 670 .Dl "etcupdate"
 671 .Pp
 672 To resolve any conflicts generated during a merge:
 673 .Pp
 674 .Dl "etcupdate resolve"
 675 .Ss Bootstrapping
 676 The
 677 .Nm
 678 utility may need to be bootstrapped before it can be used.
 679 The
 680 .Cm diff
 681 command will fail with an error about a missing reference tree if
 682 bootstrapping is needed.
 683 .Pp
 684 Bootstrapping
 685 .Nm
 686 requires a source tree that matches the currently installed world.
 687 The easiest way to ensure this is to bootstrap
 688 .Nm
 689 before updating the source tree to start the next world upgrade cycle.
 690 First,
 691 generate a reference tree:
 692 .Pp
 693 .Dl "etcupdate extract"
 694 .Pp
 695 Second,
 696 use the
 697 .Cm diff
 698 command to compare the reference tree to your current files in
 699 .Pa /etc .
 700 Undesired differences should be removed using an editor,
 701 .Xr patch 1 ,
 702 or by copying files from the reference tree
 703 .Po
 704 located at
 705 .Pa /var/db/etcupdate/current
 706 by default
 707 .Pc
 708 .
 709 .Pp
 710 If the tree at
 711 .Pa /usr/src
 712 is already newer than the currently installed world,
 713 a new tree matching the currently installed world can be checked out to
 714 a temporary location.
 715 The reference tree for
 716 .Nm
 717 can then be generated via:
 718 .Pp
 719 .Dl "etcupdate extract -s /path/to/tree"
 720 .Pp
 721 The
 722 .Cm diff
 723 command can be used as above to remove undesired differences.
 724 Afterwards,
 725 the changes in the tree at
 726 .Pa /usr/src
 727 can be merged via a regular merge.
 728 .Sh DIAGNOSTICS
 729 The following warning messages may be generated during a merge.
 730 Note that several of these warnings cover obscure cases that should occur
 731 rarely if at all in practice.
 732 For example,
 733 if a file changes from a file to a directory in the
 734 .Dq current
 735 tree
 736 and the file was modified in the destination directory,
 737 then a warning will be triggered.
 738 In general,
 739 when a warning references a pathname,
 740 the corresponding file in the destination directory is not changed by a
 741 merge operation.
 742 .Bl -diag
 743 .It "Directory mismatch: <path> (<type>)"
 744 An attempt was made to create a directory at
 745 .Pa path
 746 but an existing file of type
 747 .Dq type
 748 already exists for that path name.
 749 .It "Modified link changed: <file> (<old> became <new>)"
 750 The target of a symbolic link named
 751 .Pa file
 752 was changed from
 753 .Dq old
 754 to
 755 .Dq new
 756 in the
 757 .Dq current
 758 tree.
 759 The symbolic link has been modified to point to a target that is neither
 760 .Dq old
 761 nor
 762 .Dq new
 763 in the destination directory.
 764 .It "Modified mismatch: <file> (<new> vs <dest>)"
 765 A file named
 766 .Pa file
 767 of type
 768 .Dq new
 769 was modified in the
 770 .Dq current
 771 tree,
 772 but the file exists as a different type
 773 .Dq dest
 774 in the destination directory.
 775 .It "Modified <type> changed: <file> (<old> became <new>)"
 776 A file named
 777 .Pa file
 778 changed type from
 779 .Dq old
 780 in the
 781 .Dq previous
 782 tree to type
 783 .Dq new
 784 in the
 785 .Dq current
 786 tree.
 787 The file in the destination directory of type
 788 .Dq type
 789 has been modified,
 790 so it could not be merged automatically.
 791 .It "Modified <type> remains: <file>"
 792 The file of type
 793 .Dq type
 794 named
 795 .Pa file
 796 has been removed from the
 797 .Dq current
 798 tree,
 799 but it has been locally modified.
 800 The modified version of the file remains in the destination directory.
 801 .It "Needs update: /etc/localtime (required manual update via tzsetup(8))"
 802 The
 803 .Fa /var/db/zoneinfo
 804 file does not exist,
 805 so
 806 .Nm
 807 was not able to refresh
 808 .Fa /etc/localtime
 809 from its source file in
 810 .Fa /usr/share/zoneinfo .
 811 Running
 812 .Xr tzsetup 8
 813 will both refresh
 814 .Fa /etc/localtime
 815 and generate
 816 .Fa /var/db/zoneinfo
 817 permitting future updates to refresh
 818 .Fa /etc/localtime
 819 automatically.
 820 .It "Needs update: /etc/mail/aliases.db (required manual update via newaliases(1))"
 821 The file
 822 .Pa /etc/mail/aliases
 823 was updated during a merge with a non-empty destination directory.
 824 Due to a limitation of the
 825 .Xr newaliases 1
 826 command,
 827 .Nm
 828 was not able to automatically update the corresponding aliases database.
 829 .It "New file mismatch: <file> (<new> vs <dest>)"
 830 A new file named
 831 .Pa file
 832 of type
 833 .Dq new
 834 has been added to the
 835 .Dq current
 836 tree.
 837 A file of that name already exists in the destination directory,
 838 but it is of a different type
 839 .Dq dest .
 840 .It "New link conflict: <file> (<new> vs <dest>)"
 841 A symbolic link named
 842 .Pa file
 843 has been added to the
 844 .Dq current
 845 tree that links to
 846 .Dq new .
 847 A symbolic link of the same name already exists in the destination
 848 directory,
 849 but it links to a different target
 850 .Dq dest .
 851 .It "Non-empty directory remains: <file>"
 852 The directory
 853 .Pa file
 854 was removed from the
 855 .Dq current
 856 tree,
 857 but it contains additional files in the destination directory.
 858 These additional files as well as the directory remain.
 859 .It "Remove mismatch: <file> (<old> became <new>)"
 860 A file named
 861 .Pa file
 862 changed from type
 863 .Dq old
 864 in the
 865 .Dq previous
 866 tree to type
 867 .Dq new
 868 in the
 869 .Dq current
 870 tree,
 871 but it has been removed in the destination directory.
 872 .It "Removed file changed: <file>"
 873 A file named
 874 .Pa file
 875 was modified in the
 876 .Dq current
 877 tree,
 878 but it has been removed in the destination directory.
 879 .It "Removed link changed: <file> (<old> became <new>)"
 880 The target of a symbolic link named
 881 .Pa file
 882 was changed from
 883 .Dq old
 884 to
 885 .Dq new
 886 in the
 887 .Dq current
 888 tree,
 889 but it has been removed in the destination directory.
 890 .El
 891 .Sh SEE ALSO
 892 .Xr cap_mkdb 1 ,
 893 .Xr diff 1 ,
 894 .Xr make 1 ,
 895 .Xr newaliases 1 ,
 896 .Xr sh 1 ,
 897 .Xr mergemaster 8 ,
 898 .Xr pwd_mkdb 8 ,
 899 .Xr services_mkdb 8 ,
 900 .Xr tzsetup 8
 901 .Sh HISTORY
 902 The
 903 .Nm
 904 utility first appeared in
 905 .Fx 10.0 .
 906 .Sh AUTHORS
 907 The
 908 .Nm
 909 utility was written by
 910 .An John Baldwin Aq Mt jhb@FreeBSD.org .
 911 .Sh BUGS
 912 Rerunning a merge does not automatically delete conflicts left over from a
 913 previous merge.
 914 Any conflicts must be resolved before the merge can be rerun.
 915 It is not clear if this is a feature or a bug.
 916 .Pp
 917 There is no way to easily automate conflict resolution for specific files.
 918 For example, one can imagine a syntax along the lines of
 919 .Pp
 920 .Dl "etcupdate resolve tf /some/file"
 921 .Pp
 922 to resolve a specific conflict in an automated fashion.
 923 .Pp
 924 Bootstrapping
 925 .Nm
 926 often results in gratuitous diffs in
 927 .Pa /etc/mail/*.cf
 928 that cause conflicts in the first merge.
 929 If an object tree that matches the source tree is present when bootstrapping,
 930 then passing the
 931 .Fl B
 932 flag to the
 933 .Cm extract
 934 command can work around this.