From owner-dev-commits-doc-all@freebsd.org Fri Mar 26 22:00:23 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 697F05AEB03 for ; Fri, 26 Mar 2021 22:00:23 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4F6bWC2cH0z3p1D; Fri, 26 Mar 2021 22:00:23 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4C93521667; Fri, 26 Mar 2021 22:00:23 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 12QM0Nru076109; Fri, 26 Mar 2021 22:00:23 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 12QM0NUW076108; Fri, 26 Mar 2021 22:00:23 GMT (envelope-from git) Date: Fri, 26 Mar 2021 22:00:23 GMT Message-Id: <202103262200.12QM0NUW076108@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Daniel Ebdrup Jensen Subject: git: 7859bada69 - main - handbook/cutting-edge: Recommend etcupdate(8) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: debdrup X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 7859bada6955d3b5858ae6f43a5c23d3dc0bead6 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 26 Mar 2021 22:00:23 -0000 The branch main has been updated by debdrup: URL: https://cgit.FreeBSD.org/doc/commit/?id=7859bada6955d3b5858ae6f43a5c23d3dc0bead6 commit 7859bada6955d3b5858ae6f43a5c23d3dc0bead6 Author: Dries Michiels AuthorDate: 2021-03-26 21:47:10 +0000 Commit: Daniel Ebdrup Jensen 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]