-h

Print a short usage message

-n

Dry run. Print the actions that would be taken if the script is invoked, but take no action.

-d[n]

Set the debug level to the (optional) level n (n defaults to 1). Please note there must be no spacesbefore the optional digit n. This turns on copious debugging information.

-p

Removes all vestiges of the file from the state hashfile. This is required to allow a package to bereinstalled after it is purged; since otherwise, the real configuration file is removed, but it remainsin the hash file; and on reinstall no action is taken, since the md5sum of the new file matches that inthe hashfile. In short, remember to use this option in the postrm for every configuration file managedby ucf when the package is being purged (assuming ucf itself exists). Note: ucf does not actuallytouch the file on disk in this operation, so any file removals are still the responsibility of thecalling package.

-v

Make the script be very verbose about setting internal variables.

-s

Set the source directory (historical md5sums are expected to live in files and sub directories of thisdirectory) to foo. By default, the directory the new_file lives in is assumed to be the source direc‐tory. Setting this option overrides settings in the environment variable UCF_SOURCE_DIR, and in theconfiguration file variable conf_source_dir.

--sum-file

Force the historical md5sums to be read from this file, rather than defaulting to living in the sourcedirectory. Setting this option overrides settings in the environment variable UCF_OLD_MDSUM_FILE, andin the configuration file variable conf_old_mdsum_file.

--three-way

This turns on the option, during installation, for the user to be offered a chance to see a merge ofthe changes between old maintainer version and the new maintainer version into the local copy of theconfiguration file. If the user likes what they see, they can ask to have these changes merged in. Thisallows one to get new upstream changes merged in even while retaining local modifications to the con‐figuration file. This is accomplished by taking the configuration file and stashing it in a cache areaduring registration, and using diff3 during the install (the stashed file name is a munged version ofthe full path of the configuration file to avoid name space clashes).

--debconf-ok

Indicate that it is ok for ucf to use an already running debconf instance for prompting (it has alwaysbeen ok to use ucf when debconf is not running -- it shall invoke debconf as needed).

--debconf-template

Instruct ucf to use the named multiselect debconf template instead of the normal ucf-provided debconftemplate. The caller is responsible for ensuring that the named template exists and has a list ofchoices matching those for the default ucf template, and should set Choices-C: ${CHOICES} to ensure thereturned values match those from the default template. Note that the choices must be different accord‐ing to whether the --three-way option is also set.

--state-dir

Set the state directory to /path/to/dir instead of the default /var/lib/ucf. Used mostly for testing.USAGEThe most common case usage is pretty simple: a single line invocation in the postinst on configure, andanother single line in the postrm to tell ucf to forget about the configuration file on purge (using the

--purge

It is recommended that you also register any file being managed by ucf with the ucf registry; this associatesthe configuration file with the package it belongs to. This is done with a simple call to ucfr. Users maythen query the association between a configuration file and the package using the tool ucfq. Please see theappropriate manual pages for details.If a file maintained by maintainer scripts is being transitioned from an unprotected status to the protectionafforded by the script, the maintainer can help ease the transition by reducing the questions that may beasked at installation time. Specifically, questions should not be asked if the file in question is an unmodi‐fied version that was one shipped in a previous version of this package; and the maintainer can help bytelling the script about the historical md5sums that published versions of this file contained.The way to do this is to either create a file called <New file>.md5sum, with one md5sum on each line, (thefile names you use are ignored, except for the entry named default), or create a directory, called <Newfile>.md5sum.d, which should contain any number of files, each containing a single line, namely, the md5sum ofa previous version of <New file>. The names of these files are not important, with one exception: The filecalled default is treated specially. For example, the author personally uses either package version numbersor release code names, like 7.6.3, or potato. If none of the historical md5sums match, we are almost certainthat either the historical record of md5sums is not complete, or the user has changed the configuration file.The default historical md5sumThe exception to the rule about names mentioned earlier is that if no md5sums match, and if the file <Newfile>.md5sum.d/default exists, or if there is a line corresponding to a default file in <New file>.md5sum, itshall be used as the default md5sum of the previous version of the package assumed to have been installed onthis machine. As you can see, unless there are limited number of previously released packages (like justone), the maintainer is also making an informed guess, but the option is provided to the maintainer.If the file <New file>.md5sum, or the directory <New file>.md5sum.d does not exist, or none of the md5sumsmatch, we test the installed <Destination> file to see whether it is the same as the <New file>. If not, weask the user whether they want us to replace the file.An additional facility is also offered: optionally, ucf can store one old version of the maintainers copy ofthe configuration file, and, on upgrade, calculate the changes made in the maintainers version of the configu‐ration file, and apply that patch to the local version of the file (on user request, of course). There is alsoa preview facility where the user can inspect the results of such a merge, before asking the action to betaken.ENVIRONMENT VARIABLESThe variable UCF_FORCE_CONFFNEW, if set, forces the new file to always overwrite the installed destinationfile, while the variable UCF_FORCE_CONFFOLD, if set silently retains the installed file. UCF_FORCE_CONFFMISSis only applicable when the installed destination file does not exist (perhaps due to user removal),and forcesucf to recreate the missing file (the default behaviour is to honor the users wishes and not recreate thelocally deleted file).FILESThis script creates the file new_file.md5sum, and it may copy the file (presumably shipped with the package)<New file> to its destination, <Destination>./var/lib/ucf/hashfile, and /var/lib/ucf/hashfile.X, where X is a small integer, where previous versions of thehashfile are stored./etc/ucf.confEXAMPLESIf the package foo wants to use ucf to handle user interaction for configuration file foo.conf, a version ofwhich is provided in the package as /usr/share/foo/configuration, a simple invocation of ucf in the post instfile is all that is needed:ucf /usr/share/foo/configuration /etc/foo.confOn purge, one should tell ucf to forget about the file (see detailed examples in /usr/share/doc/ucf/examples):ucf --purge /etc/foo.conf Please note that purge can also be used to make ucf forget the previous state of thefiles, and when the package is next installed or updated, ucf will ask the user to replace the current cofigu‐ration file. Do this if you want to change your decision to not update to a maintainer provided version of theconfiguration file.The motivation for this script was to provide conffile like handling for start files for emacs lisp packages(for example, /etc/emacs21/site-start.d/50psgml-init.el ) These start files are not shipped with the package,instead, they are installed during the post installation configuration phase by the script /usr/lib/emac‐sen-common/emacs-package-install $package_name.This script is meant to be invoked by the packages install script at /usr/lib/emacsen-common/pack‐ages/install/$package_name for each flavour of installed emacsen by calling it with the proper values of newfile ( /usr/share/emacs/site-lisp/<pkg>/<pkg-init.el ), and dest file (/etc/emacs21/site-start.d/50<pkg-init.el ), and it should do the rest.