kget.8: Rewrite it a bit and fix some mdoc stuff.
[dragonfly.git] / usr.sbin / mergemaster / mergemaster.8
CommitLineData
984263bc
MD
1.\" Copyright (c) 1998-2003 Douglas Barton
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/usr.sbin/mergemaster/mergemaster.8,v 1.5.2.12 2003/03/02 02:45:01 dougb Exp $
8a7bdfea 26.\" $DragonFly: src/usr.sbin/mergemaster/mergemaster.8,v 1.5 2008/05/02 02:05:08 swildner Exp $
984263bc
MD
27.\"
28.Dd February 5, 2001
29.Dt MERGEMASTER 8
30.Os
31.Sh NAME
32.Nm mergemaster
33.Nd merge configuration files, et al during an upgrade
34.Sh SYNOPSIS
35.Nm
36.Op Fl scrvahipC
37.Op Fl m Ar /path/to/sources
38.Op Fl t Ar /path/to/temp/root
39.Op Fl d
40.Op Fl u Ar N
41.Op Fl w Ar N
42.Op Fl D Ar /path
43.Sh DESCRIPTION
44The
45.Nm
46utility is a Bourne shell script which is designed to aid you
47in updating the various configuration and other files
48associated with
9bb2a92d 49.Dx .
984263bc
MD
50It is
51.Sy HIGHLY
52recommended that you back up your
53.Pa /etc
54directory before beginning this process.
55.Pp
56The script uses
57.Pa /usr/src/etc/Makefile
58to build a temporary root environment from
59.Pa /
60down, populating that environment with the various
61files.
62You can specify a different source directory
63with the
64.Op Fl m
65command line option, or specify the destination
66directory with the
67.Op Fl D
68option.
69It then compares each file in that environment
70to its installed counterpart.
71When the script finds a
72change in the new file, or there is no installed
73version of the new file it gives you four options to
74deal with it.
75You can install the new file as is,
76delete the new file, merge the old and new
77files (as appropriate) using
78.Xr sdiff 1
79or leave the file in the temporary root environment to
80merge by hand later.
81.Pp
82By default it creates the temporary root in
83.Pa /var/tmp/temproot
84and compares the
85.Xr cvs 1
9bb2a92d 86version $Id/$DragonFly strings for files that have them, deleting
984263bc
MD
87the temporary file if the strings match.
88If there is
89no $Id string, or if the strings are different it
90compares the files themselves.
91You can
92also specify that the script ignore the $Id strings and
93compare every file.
94.Pp
95The
96.Nm
97utility checks your umask and issues a warning for anything
98other than 022. While it is not mandatory to grant
99world read permissions for most configuration files, you
100may run into problems without them.
101If you choose a
102umask other than 022 and experience trouble later this
103could be the cause.
104.Pa /etc/master.passwd
105is treated as a special case.
106If you choose to install
107this file or a merged version of it the file permissions
108are always 600 (rw-------) for security reasons.
109After
110installing an updated version of this file you should
111probably run
112.Xr pwd_mkdb 8
113with the -p option to rebuild your password databases
114and recreate
115.Pa /etc/passwd .
116.Pp
117The script uses the owner and group id's
118that the files are created with by
119.Pa /usr/src/etc/Makefile ,
120and file permissions as specified by the umask.
121Unified diffs are used by default to display any
122differences unless you choose context diffs.
123.Pp
124The
125.Nm
126utility will source scripts that you specify right before
127it starts the comparison, and after it's done running.
128The easiest way to handle this is to place the path
129to the script(s) in the appropriate variables in your
130.Pa .mergemasterrc
131file.
132The script sourced before comparison is named in
133.Ev MM_PRE_COMPARE_SCRIPT ,
134and the one sourced after the script is done is
135.Ev MM_EXIT_SCRIPT .
136This is the recommended way to specify local modifications,
137or files that you want to give special handling to.
138This includes files that you want to be deleted without
139being compared.
140Because the named scripts are sourced from within
141.Nm ,
142all of the script's variables are available for use in
143your custom script.
144You can also use
145.Pa /etc/mergemaster.rc
146which will be read before
147.Pa .mergemasterrc .
148Options specified on the command line are updated last,
149and therefore can override both files.
150.Pp
151The options are as follows:
152.Bl -tag -width Fl
153.It Fl s
154Perform a strict comparison, diff'ing every pair of files.
155This comparison is performed line by line,
156without regard to CVS $Id's.
157.It Fl c
158Use context diffs instead of unified diffs.
159.It Fl r
160Re-run
161.Nm
162on a previously cleaned directory, skipping the creation of
163the temporary root environment.
164This option is compatible
165with all other options.
166.It Fl v
167Be more verbose about the process.
168You should probably use
169this option the first time you run
170.Nm .
171This option also gives you a list of files that exist
172only in the installed version of
173.Pa /etc .
174.It Fl a
175Run automatically.
176This option will leave all the files that
177differ from the installed versions in the temporary directory
178to be dealt with by hand.
179If the
180.Pa temproot
181directory exists, it creates a new one in a previously
182non-existent directory.
183This option unsets the verbose flag,
184but is compatible with all other options.
185Setting -a makes
186-w superfluous.
187.It Fl h
188Display usage and help information.
189.It Fl i
190Automatically install any files that do not exist in the
191destination directory.
192.It Fl p
193Pre-buildworld mode.
194Compares only files known to be essential to the success of
195{build|install}world,
196including
197.Pa /etc/make.conf .
198.It Fl C
199After a standard
200.Nm
201run,
202compares your rc.conf[.local] options to the defaults.
203.It Fl m Ar /path/to/sources
204Specify the path to the directory where you want to do the
205.Xr make 1 .
206(In other words, where your sources are, but -s was already
207taken.)
208.It Fl t Ar /path/to/temp/root
209Create the temporary root environment in
210.Pa /path/to/temp/root
211instead of the default
212.Pa /var/tmp/temproot .
213.It Fl d
214Add the date and time to the name of the temporary
215root directory.
216If -t is specified, this option must
217follow it if you want the date added too.
218.It Fl u Ar N
219Specify a numeric umask.
220The default is 022.
221.It Fl w Ar N
222Supply an alternate screen width to the
223.Xr sdiff 1
224command in numbers of columns.
225The default is 80.
226.It Fl D Ar /path
227Specify the destination directory for the installed files.
228.El
229.Sh ENVIRONMENT
230The
231.Nm
232utility uses the
233.Ev PAGER
234environment variable if set.
235Otherwise it uses
236.Xr more 1 .
237If
238.Ev PAGER
239specifies a program outside
240its
241limited
242.Ev PATH
243without specifying the full path,
244.Nm
245prompts you with options on how to proceed.
246The
247.Ev MM_PRE_COMPARE_SCRIPT
248and
249.Ev MM_EXIT_SCRIPT
250variables are used as described above.
251Other variables that are used by the script internally
252can be specified in
253.Pa .mergemasterrc
254as described in more detail below.
984263bc
MD
255.Sh FILES
256.Bl -tag -width $HOME/.mergemasterrc -compact
257.It Pa /etc/mergemaster.rc
258.It Pa $HOME/.mergemasterrc
259.El
260.Pp
261The
262.Nm
263utility will . (source) these files if they exist.
264Command line options
265will override rc file options.
266.Pa $HOME/.mergemasterrc
267overrides
268.Pa /etc/mergemaster.rc .
269Here is an example
270with all values commented out:
984263bc
MD
271.Bd -literal
272# These are options for mergemaster, with their default values listed
273# The following options have command line overrides
274#
275# Directory to install the temporary root environment into
276#TEMPROOT='/var/tmp/temproot'
277#
278# Strict comparison bypasses the CVS $Id tests and compares every file
279#STRICT=no
280#
281# Type of diff, such as unified, context, etc.
282#DIFF_FLAG='-u'
283#
284# Additional options for diff. This will get unset when using -s.
9bb2a92d 285#DIFF_OPTIONS='-I$\&DragonFly:.*[$]' # Ignores CVS Id tags
984263bc
MD
286#
287# Verbose mode includes more details and additional checks
288#VERBOSE=
289#
290# Automatically install files that do not exist on the system already
291#AUTO_INSTALL=
292#
293# Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf
294#COMP_CONFS=yes
295#
296# Sourcedir is the directory to do the 'make' in (where the new files are)
297#SOURCEDIR='/usr/src/etc'
298#
299# The umask for mergemaster to compare the default file's modes to
300#NEW_UMASK=022
301#
302# Specify the destination directory for the installed files
303#DESTDIR=
304#
305# The following options have no command line overrides
306# For those who just cannot stand including the full path to PAGER
307#DONT_CHECK_PAGER=
308#
309# If you set 'yes' above, make sure to include the PATH to your pager
310#PATH=/bin:/usr/bin:/usr/sbin
311#
312# Don't compare the old and new motd files
313#IGNORE_MOTD=yes
314#
315# Specify the path to scripts to run before the comparison starts,
316# and/or after the script has finished its work
317#MM_PRE_COMPARE_SCRIPT=
318#MM_EXIT_SCRIPT=
319.Ed
49781055
SW
320.Sh EXAMPLES
321Typically all you will need to do is type
322.Nm
323at the prompt and the script will do all the work for you.
324.Pp
325To use context diff's and have
326.Nm
327explain more things as it goes along, use:
328.Pp
329.Dl # mergemaster -cv
330.Pp
331To specify that
332.Nm
333put the temporary root environment in
334.Pa /usr/tmp/root ,
335use:
336.Pp
337.Dl # mergemaster -t /usr/tmp/root
338.Pp
339To specify a 110 column screen with a strict
340comparison, use:
341.Pp
342.Dl # mergemaster -sw 110
343.Sh DIAGNOSTICS
344Exit status is 0 on successful completion, or if the user bails out
345manually at some point during execution.
346.Pp
347Exit status is 1 if it fails for one of the following reasons:
348.Pp
349Invalid command line option
350.Pp
351Failure to create the temporary root environment
352.Pp
353Failure to populate the temporary root
984263bc
MD
354.Sh SEE ALSO
355.Xr cvs 1 ,
356.Xr diff 1 ,
357.Xr make 1 ,
358.Xr more 1 ,
359.Xr sdiff 1 ,
360.Xr pwd_mkdb 8
361.Pp
362.Pa /usr/src/etc/Makefile
363.Rs
364.%O http://www.FreeBSD.org/doc/handbook/makeworld.html
365.%T The Cutting Edge (using make world)
366.%A Nik Clayton
367.Re
984263bc
MD
368.Sh HISTORY
369The
370.Nm
371utility was first publicly available on one of my
372web pages in a much simpler form under the name
373.Pa comproot
374on 13 March 1998. The idea for creating the
375temporary root environment comes from Nik Clayton's
376make world tutorial which is referenced above.
377.Sh AUTHORS
378This manual page and the script itself were written by
379.An Douglas Barton Aq DougB@FreeBSD.org .
380.Sh BUGS
381There are no known bugs.
382Please report any problems,
383comments or suggestions to the author.
384Several of the
385improvements to this program have come from user
386suggestions.
387Thank you.