Date: Fri, 26 Mar 2021 22:00:23 GMT From: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 7859bada69 - main - handbook/cutting-edge: Recommend etcupdate(8) Message-ID: <202103262200.12QM0NUW076108@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by debdrup: URL: https://cgit.FreeBSD.org/doc/commit/?id=7859bada6955d3b5858ae6f43a5c23d3dc0bead6 commit 7859bada6955d3b5858ae6f43a5c23d3dc0bead6 Author: Dries Michiels <driesm.michiels@gmail.com> AuthorDate: 2021-03-26 21:47:10 +0000 Commit: Daniel Ebdrup Jensen <debdrup@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]
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202103262200.12QM0NUW076108>