From owner-svn-src-all@FreeBSD.ORG Mon Nov 3 00:13:22 2014 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 609E8B18; Mon, 3 Nov 2014 00:13:22 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4BD06935; Mon, 3 Nov 2014 00:13:22 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id sA30DMIQ026345; Mon, 3 Nov 2014 00:13:22 GMT (envelope-from jhb@FreeBSD.org) Received: (from jhb@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id sA30DMpf026344; Mon, 3 Nov 2014 00:13:22 GMT (envelope-from jhb@FreeBSD.org) Message-Id: <201411030013.sA30DMpf026344@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: jhb set sender to jhb@FreeBSD.org using -f From: John Baldwin Date: Mon, 3 Nov 2014 00:13:22 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org Subject: svn commit: r273998 - in stable: 10/usr.sbin/etcupdate 8/usr.sbin/etcupdate 9/usr.sbin/etcupdate X-SVN-Group: stable-9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 03 Nov 2014 00:13:22 -0000 Author: jhb Date: Mon Nov 3 00:13:20 2014 New Revision: 273998 URL: https://svnweb.freebsd.org/changeset/base/273998 Log: MFC 273834: Rework the EXAMPLES section to be a bit clearer. - Add an example of using etcupdate diff. - Create a subsection on bootstrapping that is below the simple examples. This should make it clearer that 'etcupdate extract' is a one-time operation and not part of the common workflow. It also adds more suggestions on when bootstrapping is needed and additional steps to make future merges simpler. Modified: stable/9/usr.sbin/etcupdate/etcupdate.8 Directory Properties: stable/9/usr.sbin/etcupdate/ (props changed) Changes in other areas also in this revision: Modified: stable/10/usr.sbin/etcupdate/etcupdate.8 stable/8/usr.sbin/etcupdate/etcupdate.8 Directory Properties: stable/10/ (props changed) stable/8/usr.sbin/etcupdate/ (props changed) Modified: stable/9/usr.sbin/etcupdate/etcupdate.8 ============================================================================== --- stable/9/usr.sbin/etcupdate/etcupdate.8 Sun Nov 2 23:30:50 2014 (r273997) +++ stable/9/usr.sbin/etcupdate/etcupdate.8 Mon Nov 3 00:13:20 2014 (r273998) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 9, 2013 +.Dd October 29, 2014 .Dt ETCUPDATE 8 .Os .Sh NAME @@ -608,12 +608,11 @@ Default log file. .Sh EXIT STATUS .Ex -std .Sh EXAMPLES -If the source tree matches the currently installed world, -then the following can be used to bootstrap -.Nm -so that it can be used for future upgrades: +To compare the files in +.Pa /etc +with the stock versions: .Pp -.Dl "etcupdate extract" +.Dl "etcupdate diff" .Pp To merge changes after an upgrade via the buildworld and installworld process: .Pp @@ -622,6 +621,59 @@ To merge changes after an upgrade via th To resolve any conflicts generated during a merge: .Pp .Dl "etcupdate resolve" +.Ss Bootstrapping +The +.Nm +utility may need to be bootstrapped before it can be used. +The +.Cm diff +command will fail with an error about a missing reference tree if +bootstrapping is needed. +.Pp +Bootstrapping +.Nm +requires a source tree that matches the currently installed world. +The easiest way to ensure this is to bootstrap +.Nm +before updating the source tree to start the next world upgrade cycle. +First, +generate a reference tree: +.Pp +.Dl "etcupdate extract" +.Pp +Second, +use the +.Cm diff +command to compare the reference tree to your current files in +.Pa /etc . +Undesired differences should be removed using an editor, +.Xr patch 1 , +or by copying files from the reference tree +.Po +located at +.Pa /var/db/etcupdate/current +by default +.Pc +. +.Pp +If the tree at +.Pa /usr/src +is already newer than the currently installed world, +a new tree matching the currently installed world can be checked out to +a temporary location. +The reference tree for +.Nm +can then be generated via: +.Pp +.Dl "etcupdate extract -s /path/to/tree" +.Pp +The +.Cm diff +command can be used as above to remove undesired differences. +Afterwards, +the changes in the tree at +.Pa /usr/src +can be merged via a regular merge. .Sh DIAGNOSTICS The following warning messages may be generated during a merge. Note that several of these warnings cover obscure cases that should occur