Dispatch-conf

 is Article description::a utility included with [[Portage, used to safely manage configuration file updates.]] It allows system administrators to review configuration file changes made by Portage, either by using the new configuration as-is, by rejecting changes, or by selectively merging modifications. Portage will indicate when config files need updating.

is an important tool to manage the issue of transitioning configuration across package updates. This is a general problem with any software: some version changes will modify the behavior of software, such that the previous configuration parameters become no longer pertinent to the new version. New configuration options may be added, removed, their meaning may be changed or the names or the format of each directive may change. Each software project manages this in it's own way. Some projects have robust configuration version tracking and can automatically transfer configuration from one version to another; some projects may have issues between major versions, or if updating from much older versions; for some projects, updating while trying to preserve previous configurations may cause issues or even be impossible.

There is a long-standing Unix convention of using plain text files, often with similar syntax, for storing configuration. Often, major updates would require manual migration of these files, or risk them becoming outdated. This may seem cumbersome today, but it remains a very robust way to manage configuration, and avoids ambiguity of how the configuration directives may change between versions, which is important for many - sometimes critical - services such as Internet servers. aims to permit Gentoo administrators to smoothly manage their configuration across package updates, providing a standardized way to maintain configuration across updates for many packages, without the user needing to manually migrate everything.

permits rollback, so any mistakes can be reverted. Changes made to config files will be saved in the archive directory; alternatively it can integrate with to allow for version-controlled configuration file management. will automatically update config files that the user has never modified, or that differ from the current version only in CVS cruft, comments, or white space.

will check all directories in the CONFIG_PROTECT environment variable for changes. Any config files found in paths in the CONFIG_PROTECT_MASK environment variable will not be protected and will automatically be overwritten.

Files
The configuration file is. The directory referenced by the archive-dir variable in this file may need to be created.

RCS (revision control system) integration
When is configured to integrate with, it will store all changes in.

Install revision control system:

This process of configuration is as simple as editing the configuration file to include the following:

Administrators can then view the differences using the utilities like  as well as roll-back changes using. The utilities work with file locking itself, so the moment you want to use it in your administrative tasks, understand that:


 * only stores the changes made when the package suggests to alter the file. Changes you made afterwards are not registered yet
 * when you check out a file, will want to write the file to the file system, so make sure you backup your existing file first, or work with standard output (see later)
 * if you want to check in a file, you first need to take a lock on said file. Also, make sure you opt not to remove the working file

To view the commit history on :

{{Cmd|rlog /etc/config-archive/etc/conf.d/udev,v|output= RCS file: /etc/config-archive/etc/conf.d/udev,v Working file: udev head: 1.1 branch: locks: strict access list: symbolic names: keyword substitution: kv total revisions: 2;    selected revisions: 2 description: Archived config file.

revision 1.1 date: 2011/06/15 18:14:59; author: root;  state: Exp; branches: 1.1.1; dispatch-conf update.

revision 1.1.1.1 date: 2011/06/15 18:14:59; author: root;  state: Exp;  lines: +3 -2 dispatch-conf update.

=
================================================================ }}

If you want to roll back to a particular version, a simple way to do so is to check out a previous version:

After making your final changes (you can use the backup to merge any changes made later), check in the file again:

Edit the file, and finally check in the changes:

Color diff output
Reading changes in all grey text can be a bit annoying. Fortunately, modern versions of have a   switch, which displays the different types of changes in different colors. Configuration is simple - change the diff line in the config file to:

Alternatively, the package can be used. Install colordiff with:

Then change the config to use it:

Use (g)vimdiff to merge changes
You may wish to try (g)vimdiff instead of the default method of merging files. To do this, modify the configuration file by changing the merge line:

You can also use vimdiff (for gvimdiff use  option moreover) to merge changes. If you want to use neovim, replace  at the end with

Some useful commands related to merge with vimdiff:

"]c" : jump to next change "[c" : jump to previous change "CTRL-W " or "CTRL-W " : go to the other window "do" (diff obtain): get the text of the highlighted block from the other window "dp" (diff put) : put the text of the highlighted block to the other window "zo" : open fold under the cursor "zc" : close fold under the cursor "zr" : open all folds ":wqa" : write and exit

See the Vim documentation for further help.

Using imediff2 to merge changes
Another merge alternative is. This simple tool allows using just a few keys to toggle between options. Primarily, this is done through the or  keys. Also, the key will open the user's favorite editor set by the EDITOR shell variable for manual merging.

To use with dispatch-conf, first install imediff2:

Then, configure :

Invocation
should be run as root, as configuration files are usually owned by root:

The AMD64 Handbook and the man page contain further information on usage: