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