usr.sbin/etcupdate/etcupdate.8

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