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