Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MERGEMASTER(8)		    System Manager's Manual		MERGEMASTER(8)

NAME
       mergemaster -- merge configuration files, et al during an upgrade

SYNOPSIS
       mergemaster    [-scrvhpCP]    [-a|iFU]	[--run-updates=[always|never]]
		   [-m /path/to/sources] [-t /path/to/temp/root] [-d]  [-u  N]
		   [-w N] [-A Target architecture] [-D /destdir/path]

DESCRIPTION
       The  mergemaster	 utility  is  deprecated  and  may not be available in
       FreeBSD 14.0 or later.  Users are advised to use	etcupdate(8)  instead.

       The  mergemaster	 utility is a Bourne shell script which	is designed to
       aid you in updating the various configuration and other	files  associ-
       ated with FreeBSD.  It is HIGHLY	recommended that you back up your /etc
       directory before	beginning this process.

       The script uses /usr/src/Makefile to build a temporary root environment
       from  /	down, populating that environment with the various files.  You
       can specify a different source directory	with the -m command  line  op-
       tion, or	specify	the destination	directory with the -D option.  It then
       compares	 each  file  in	that environment to its	installed counterpart.
       When the	script finds a change in the new file,	or  there  is  no  in-
       stalled	version	of the new file	it gives you four options to deal with
       it.  You	can install the	new file as is,	delete the new file, merge the
       old and new files (as appropriate) using	sdiff(1) or leave the file  in
       the temporary root environment to merge by hand later.

       By  default it creates the temporary root in /var/tmp/temproot and com-
       pares the Version Control System	(VCS) Id strings ($FreeBSD) for	 files
       that  have  them, deleting the temporary	file if	the strings match.  If
       there is	no Id string, or if the	strings	are different it compares  the
       files  themselves.   You	can also specify that the script ignore	the Id
       strings and compare every file with the -s option.  Using the -F	option
       mergemaster will	install	the new	file for you if	they  differ  only  by
       VCS strings.

       The  merge  menu	option is designed to let you easily combine your cus-
       tomizations from	the old	version	of a file into the new one.  While you
       can use the merge function to incorporate changes from files  that  you
       have not	customized, it is not recommended.

       The mergemaster utility checks your umask and issues a warning for any-
       thing  other  than  022.	 While it is not mandatory to grant world read
       permissions for most configuration files, you  may  run	into  problems
       without	them.	If  you	 choose	 a umask other than 022	and experience
       trouble later this could	be the cause.  /etc/master.passwd  is  treated
       as a special case.  If you choose to install this file or a merged ver-
       sion of it the file permissions are always 600 (rw-------) for security
       reasons.	  After	 installing an updated version of this file you	should
       probably	run pwd_mkdb(8)	with the -p option to  rebuild	your  password
       databases and recreate /etc/passwd.

       The script uses the owner and group ids that the	files are created with
       by  /usr/src/etc/Makefile,  and	file  permissions  as specified	by the
       umask.  Unified diffs are used by default to  display  any  differences
       unless you choose context diffs.

       The  mergemaster	utility	will source scripts that you specify right be-
       fore it starts the comparison, and after	it is done running.  The easi-
       est way to handle this is to place the path to the script(s) in the ap-
       propriate variables in your .mergemasterrc file.	  The  script  sourced
       before  comparison  is  named  in  MM_PRE_COMPARE_SCRIPT,  and  the one
       sourced after the script	is done	is MM_EXIT_SCRIPT.  This is the	recom-
       mended way to specify local modifications, or files that	 you  want  to
       give  special  handling	to.   This  includes files that	you want to be
       deleted without being compared.	Because	the named scripts are  sourced
       from  within  mergemaster,  all of the script's variables are available
       for use in your custom script.  You can	also  use  /etc/mergemaster.rc
       which  will  be	read  before .mergemasterrc.  Options specified	on the
       command line are	updated	last, and therefore can	override both files.

       When the	comparison is done if there are	any  files  remaining  in  the
       temproot	 directory they	will be	listed,	and if the -a option is	not in
       use the user will be given the option of	deleting the  temproot	direc-
       tory.   If  there  are  no files	remaining in the temproot directory it
       will be deleted.

       The options are as follows:

       -s	   Perform a strict comparison,	diffing	every pair  of	files.
		   This	 comparison  is	performed line by line,	without	regard
		   to VCS Ids.

       -c	   Use context diffs instead of	unified	diffs.

       -r	   Re-run mergemaster on a previously cleaned directory, skip-
		   ping	the creation of	the temporary root environment.	  This
		   option is compatible	with all other options.

       -v	   Be more verbose about the process.  You should probably use
		   this	 option	 the first time	you run	mergemaster.  This op-
		   tion	also gives you a list of files that exist only in  the
		   installed version of	/etc.

       -a	   Run	automatically.	 This  option will leave all the files
		   that	differ from the	installed versions  in	the  temporary
		   directory to	be dealt with by hand.	If the temproot	direc-
		   tory	exists,	it creates a new one in	a previously non-exis-
		   tent	 directory.   This option unsets the verbose flag, and
		   is not compatible with -i, -F, or -U.  Setting -a makes  -w
		   superfluous.

       -h	   Display usage and help information.

       -i	   Automatically  install  any	files that do not exist	in the
		   destination directory.

       -p	   Pre-buildworld mode.	 Compares only files known to  be  es-
		   sential  to	the  success  of  {build|install}world,	 i.e.,
		   /etc/group and /etc/master.passwd.

       -F	   If the files	differ only by VCS Id ($FreeBSD)  install  the
		   new file.

       -C	   After   a   standard	  mergemaster	run,   compares	  your
		   rc.conf[.local] options to the defaults.

       -P	   Preserve	 files	    that      you      replace	    in
		   /var/tmp/mergemaster/preserved-files-_date_,	or another di-
		   rectory you specify in your mergemaster rc file.

       -U	   Attempt to auto upgrade files that have not been user modi-
		   fied.  This option can be dangerous when there are critical
		   changes  in	the new	versions that affect your running sys-
		   tem.

       --run-updates=[always|never]
		   Specify always or never to run newaliases,  pwd_mkdb,  etc.
		   at  the end of the comparison run.  If this option is omit-
		   ted the default is to prompt	the user for  each  update  as
		   necessary.

       -m /path/to/sources
		   Specify  the	path to	the directory where you	want to	do the
		   make(1).  (In other words, where your sources are,  but  -s
		   was	already	 taken.)  In older versions of mergemaster the
		   path	to src/etc was required.  mergemaster will convert the
		   path	if this	older method is	used.

       -t /path/to/temp/root
		   Create the temporary	root environment in /path/to/temp/root
		   instead of the default /var/tmp/temproot.

       -d	   Add the date	and time to the	name of	the temporary root di-
		   rectory.  If	-t is specified, this option must follow it if
		   you want the	date added too.

       -u N	   Specify a numeric umask.  The default is 022.

       -w N	   Supply an alternate screen width to the sdiff(1) command in
		   numbers of columns.	The default is 80.

       -A Target architecture
		   Specify an alternative TARGET_ARCH architecture name.

       -D /path	   Specify the destination directory for the installed files.

ENVIRONMENT
       The mergemaster utility uses the	PAGER  environment  variable  if  set.
       Otherwise  it  uses  less(1).  If PAGER specifies a program outside its
       limited PATH without specifying the full	path, mergemaster prompts  you
       with   options  on  how	to  proceed.   The  MM_PRE_COMPARE_SCRIPT  and
       MM_EXIT_SCRIPT variables	are used as described above.  Other  variables
       that   are   used   by  the  script  internally	can  be	 specified  in
       .mergemasterrc as described in more detail below.

FILES
       /etc/mergemaster.rc
       $HOME/.mergemasterrc

       The mergemaster utility will . (source)	these  files  if  they	exist.
       Command	  line	  options    will    override	 rc    file   options.
       $HOME/.mergemasterrc overrides /etc/mergemaster.rc.  Here is an example
       with all	values commented out:

       # These are options for mergemaster, with their default values listed
       # The following options have command line overrides
       #
       # The target architecture (-A, unset by default)
       #ARCHSTRING='TARGET_ARCH=<foo>'
       #
       # Sourcedir is the directory to do the 'make' in	(-m)
       #SOURCEDIR='/usr/src'
       #
       # Directory to install the temporary root environment into (-t)
       #TEMPROOT='/var/tmp/temproot'
       #
       # Specify the destination directory for the installed files (-D)
       #DESTDIR=
       #
       # Strict	comparison skips the VCS Id test and compares every file (-s)
       #STRICT=no
       #
       # Type of diff, such as unified,	context, etc. (-c)
       #DIFF_FLAG='-u'
       #
       # Install the new file if it differs only by VCS	Id ($FreeBSD, -F)
       #FREEBSD_ID=
       #
       # Verbose mode includes more details and	additional checks (-v)
       #VERBOSE=
       #
       # Automatically install files that do not exist on the system already (-i)
       #AUTO_INSTALL=
       #
       # Automatically upgrade files that have not been	user modified (-U)
       # ***DANGEROUS***
       #AUTO_UPGRADE=
       #
       # Either	always or never	run newaliases,	pwd_mkdb at the	end (--run-updates)
       #RUN_UPDATES=
       #
       # Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf (-C)
       #COMP_CONFS=
       #
       # Preserve files	that you replace (-P)
       #PRESERVE_FILES=
       #PRESERVE_FILES_DIR=/var/tmp/mergemaster/preserved-files-`date +%y%m%d-%H%M%S`
       #
       # The umask for mergemaster to compare the default file's modes to (-u)
       #NEW_UMASK=022
       #
       # The following options have no command line overrides
       #
       # Files to always avoid comparing
       #IGNORE_FILES='/etc/motd	/etc/printcap foo bar'
       #
       # Additional options for	diff.  This will get unset when	using -s.
       #DIFF_OPTIONS='-Bb'     # Ignore	changes	in whitespace
       #
       # Location to store the list of mtree values for	AUTO_UPGRADE purposes
       #MTREEDB='/var/db'
       #
       # For those who just cannot stand including the full path to PAGER
       #DONT_CHECK_PAGER=
       #
       # If you	set 'yes' above, make sure to include the PATH to your pager
       #PATH=/bin:/usr/bin:/usr/sbin
       #
       # Delete	stale files in /etc/rc.d without prompting
       #DELETE_STALE_RC_FILES=
       #
       # Specify the path to scripts to	run before the comparison starts,
       # and/or	after the script has finished its work
       #MM_PRE_COMPARE_SCRIPT=
       #MM_EXIT_SCRIPT=

EXIT STATUS
       Exit status is 0	on successful completion, or if	 the  user  bails  out
       manually	at some	point during execution.

       Exit status is 1	if it fails for	one of the following reasons:

       Invalid command line option

       Failure to create the temporary root environment

       Failure to populate the temporary root

       Presence	of the 'nodev' option in _DESTDIR_/etc/fstab

       Failure to install a file

EXAMPLES
       Typically all you will need to do is type mergemaster at	the prompt and
       the script will do all the work for you.

       To  use	context	 diffs	and have mergemaster explain more things as it
       goes along, use:

	     # mergemaster -cv

       To specify that mergemaster  put	 the  temporary	 root  environment  in
       /usr/tmp/root, use:

	     # mergemaster -t /usr/tmp/root

       To specify a 110	column screen with a strict comparison,	use:

	     # mergemaster -sw 110

SEE ALSO
       diff(1),	make(1), less(1), sdiff(1), etcupdate(8), pwd_mkdb(8)

       /usr/src/etc/Makefile

       The			    FreeBSD			     Handbook,
       https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld.

HISTORY
       The mergemaster utility was first publicly available on one of  my  web
       pages  in a much	simpler	form under the name comproot on	13 March 1998.
       The idea	for creating the temporary root	 environment  comes  from  Nik
       Clayton's make world tutorial which is referenced above.

AUTHORS
       This  manual  page and the script itself	were written by	Douglas	Barton
       <dougb@FreeBSD.org>.

FreeBSD	13.2			 March 2, 2023			MERGEMASTER(8)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mergemaster&manpath=FreeBSD+14.0-RELEASE+and+Ports>

home | help