git: 7859bada69 - main - handbook/cutting-edge: Recommend etcupdate(8)

[Daniel Ebdrup Jensen]

The branch main has been updated by debdrup:

URL: https://cgit.FreeBSD.org/doc/commit/?id=7859bada6955d3b5858ae6f43a5c23d3dc0bead6

commit 7859bada6955d3b5858ae6f43a5c23d3dc0bead6
Author:     Dries Michiels <driesm.michiels at gmail.com>
AuthorDate: 2021-03-26 21:47:10 +0000
Commit:     Daniel Ebdrup Jensen <debdrup at FreeBSD.org>
CommitDate: 2021-03-26 21:47:10 +0000

    handbook/cutting-edge: Recommend etcupdate(8)
    
    Since etcupdate(8) has lived in base since 10.0 and seen plenty of use
    by both committers and contributors, it's time to recommend using it.
    
    Reviewed by:    jhb (prior version)
    Differential Revision:  https://reviews.freebsd.org/D27848
---
 .../en/books/handbook/cutting-edge/_index.adoc     | 52 ++++++++++++++++++++--
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
index a9512d215e..ee11b2951b 100644
--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
@@ -617,9 +617,10 @@ check /usr/src/UPDATING  <.>
 # make -j4 buildworld  <.>
 # make -j4 kernel      <.>
 # shutdown -r now      <.>
+# etcupdate -p         <.>
 # cd /usr/src          <.>
 # make installworld    <.>
-# mergemaster -Ui      <.>
+# etcupdate -B         <.>
 # shutdown -r now      <.>
 ....
 
@@ -635,6 +636,8 @@ check /usr/src/UPDATING  <.>
 
 <.> Reboot the system to the new kernel.
 
+<.> Update and merge configuraton files in [.filename]#/etc/# required before installworld.
+
 <.> Go to the source directory.
 
 <.> Install the world.
@@ -863,11 +866,54 @@ If a custom kernel was built, `KERNCONF` must also be set to use the new custom
 A few final tasks complete the update.
 Any modified configuration files are merged with the new versions, outdated libraries are located and removed, then the system is restarted.
 
+[[updating-src-completing-merge-etcupdate]]
+==== Merging Configuration Files with man:etcupdate[8]
+
+man:etcupdate[8] is a tool for managing updates to files that are not updated as part of an installworld such as files located in [.filename]#/etc/#.
+It manages updates by doing a three-way merge of changes made to these files against the local versions.
+It is also designed to minimize the amount of user intervention, in contrast to man:mergemaster[8]'s interactive prompts.
+
+[NOTE]
+====
+In general, man:etcupdate[8] does not need any specific arguments for its job.
+There is however a handy in between command for sanity checking what will be done the first time man:etcupdate[8] is used:
+
+[source,shell]
+....
+# etcupdate diff
+....
+
+This command allows the user to audit configuration changes.
+====
+
+If man:etcupdate[8] is not able to merge a file automatically, the merge conflicts can be resolved with manual interaction by issuing:
+
+[source,shell]
+....
+# etcupdate resolve
+....
+
+[WARNING]
+====
+When switching from man:mergemaster[8] to man:etcupdate[8], the first run might merge changes incorrectly generating spurious conflicts.
+To prevent this, perform the following steps *before* updating sources and building the new world:
+
+[source,shell]
+....
+# etcupdate bootstrap <.>
+# etcupdate diff <.>
+....
+
+<.> Bootstrap the database of stock [.filename]#/etc# files, for more information see man:etcupdate[8].
+
+<.> Check the diff after bootstrapping. Trim any local changes that are no longer needed to reduce the chance of conflicts in future updates.
+====
+
 [[updating-src-completing-merge-mergemaster]]
 ==== Merging Configuration Files with man:mergemaster[8]
 
-man:mergemaster[8] provides an easy way to merge changes that have been made to system configuration files with new versions of those files.
-
+man:mergemaster[8] provides a way to merge changes that have been made to system configuration files with new versions of those files.
+man:mergemaster[8] is an alternative to the preferred man:etcupdate[8]
 With `-Ui`, man:mergemaster[8] automatically updates files that have not been user-modified and installs new files that are not already present:
 
 [source,shell]