Gentoo Wiki


This article is part of the Tips & Tricks series.
Terminals / Shells Network X Window System Portage System Filesystems Kernel Other



dispatch-conf is a script designed to ease /etc and other config file updates. Its claim to fame is that it can automatically update any scripts that have easy changes to comments, or that haven't been changed between updates. Unlike etc-update it also creates backups and has more advanced options for configuration file management.

If you want to know more about what the dispatch-conf and etc-update tools do, read emerge --help --config.


No installation is necessary, it comes with portage so you already have this great tool installed! All you have to do is configure it via the config file:

File: /etc/dispatch-conf.conf
# Directory to archive replaced configs

# Use rcs for storing files in the archive directory?
# (yes or no)

# Diff for display
# %s old file
# %s new file
diff="diff -Nu %s %s"

# Automerge files comprising only CVS interpolations (e.g. Header or Id)
# (yes or no)

# Automerge files comprising only whitespace and/or comments
# (yes or no)

# Automerge files that the user hasn't modified
# (yes or no)

# Ignore a version that is identical to the previously merged version,
# even though it is different from the current user modified version
# (yes or no)

Backup Directory

dispatch-conf keeps copies of changed files in a directory is specified in the config files. By default this is /etc/config-archive

Tip: If you have another partition or hard drive, you might consider putting the config-archive there, so that if your drive with /etc on it gets trashed, you can use dispatch-conf's records to rebuild your config.

Advanced Backups

dispatch-conf also has the ability to use the rcs (revision control system) version management tool (similar to, and precursor to, cvs or subversion) to create a log of all changes ever made to config files.

To enable rcs backups, install rcs with emerge -av rcs and set use-rcs=yes in /etc/dispatch-conf.conf.

rcs basically creates diffs of the changes between two files. You can find out more about diff on Wikipedia.

Some useful commands related to rcs :

# rcs2log -v /etc/config-archive/etc/init.d/fail2ban,v

Use colordiff to view changes

Reading changes in all grey text can be a bit annoying. Fortunately there's an aternative called colordiff that displays the different types of changes in different colors. Configuration is simple, first install colordiff with emerge -av colordiff. Now change the diff line in the config file to:

File: /etc/dispatch-conf.conf
diff="colordiff -Nu '%s' '%s' | less --no-init --QUIT-AT-EOF"

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 /etc/dispatch-conf.conf configuration file by changing the merge line:

File: /etc/dispatch-conf.conf
merge="vimdiff -c \'saveas %s\' -c next -c \'setlocal noma readonly\' -c prev %s %s"

You can also use vimdiff (for gvimdiff use -f flag moreover) to merge changes.

Note: The left pane will hold the original config file saved as the merge output, so make changes in the left pane and save that pane. To help you remember the right hand pane (containing the new config file) will be marked unmodifiable and read-only.

Some useful commands related to merge with vimdiff :

See also the Vim documentation for further help.

Use xxdiff to view and merge changes

A further alternative is to use a gui tool to view and merge changes, such as xxdiff. To do so, install xxdiff with: emerge -av xxdiff and alter the diff line and add a merge line to the config file:

File: /etc/dispatch-conf.conf
# xxdiff for viewing differences:
diff="xxdiff %s %s"

# xxdiff for merging:
merge="xxdiff -X -m --resource 'Show.PaneMergedView:true' -O -M %s %s %s"

Note: -X alters error code responce to meet dispatch-conf requirements.


Auto Merging

Run dispatch-conf. If you have any config files that need updating the script will go through and see if it can automerge any of them for you. You will then see a diff of the first config it found that it could not auto-merge.

Manually Merging

If there are files that can't be auto merged, you will see an output like this, if using the default configuration:

Code: dispatch-conf
--- /etc/portage/package.keywords       2006-01-23 16:10:44.000000000 -0600
+++ /etc/portage/._cfg0000_package.keywords     2006-01-22 13:52:51.000000000 -0600
@@ -7,4 +7,4 @@
 dev-util/intltool ~x86
-# sys-block/gparted ~x86
+sys-block/gparted ~x86
 www-client/prozilla ~x86
 www-client/mozilla-firefox ~x86
@@ -41,3 +41,3 @@
 x11-libs/pango ~x86
-gnome-extra/libgtkhtml ~x86
+gnome-extra/gtkhtml ~x86
 mail-client/evolution ~x86

>> (1 of 1) -- /etc/portage/package.keywords
>> q quit, h help, n next, e edit-new, z zap-new, u use-new
   m merge, t toggle-merge, l look-merge:
Note: Use the Up and Down arrows as well as PgUp and PgDn to navigate if the ouput is larger and you don't see the footer of options.

In the above example the file being updated is /etc/portage/package.keywords.

At this point you can:

The t and l options don't really come into play until the m option has been used.

If you choose to merge the files, pressing m will compare difference groups side by side, with the original file on the left and the new file on the right. At the prompt (%) press l to choose the left side as the section to keep or r to keep the right side (part from new file).

Changes will be placed in a new, merged, file. If you run out of changes or press q at the prompt you will return to above diff display, only this time the merged file you just created will be compared the original. Pressing t compares the original with the pre-merged file once again. This means that the use-new option picks either the merged or pre-merged file depending on which is displayed on the screen.

Tip: If in an X term, maximize your terminal window or merge display may be less than side-by-side.

Working with dispatch-conf

The first time you update a config file with the new untouched config file, dispatch-conf will copy it to your archive directory in the corresponding location with a '.dist'. From this point on, it will compare 'current' and 'archive.dist'. If the files are the same (and replace-unmodified=yes in /etc/dispatch-conf.conf), it will auto-merge.

As the collection grows, dispatch-conf gets smarter; it will have to ask you about fewer and fewer files each time it runs.

Thus, if, for instance, you always wanted to auto-merge the files in /etc/init.d and your config archive directory is /etc/config-archive: for x in /etc/init.d/*; do cp "$x" "/etc/config-archive$x.dist"; done

Example Session

A user is merging the system package set, new /etc/bash/._cfg0000_bashrc file appears and the user needs update it into their /etc/bash/bashrc. Now the user runs dispatch-conf, which finds the new file to merge and displays the differences.

The first item displayed is the files being compared:

--- /etc/bash/bashrc    2005-08-11 22:29:36.000000000 +0200
+++ /etc/bash/._cfg0000_bashrc  2006-09-24 15:29:13.000000000 +0200

The user decides to select m to interactively change their config. The users selected editing method is run and they make the desired changes, which are saved to /etc/bash/._mrg0000_bashrc, which is now considered the new version. dispatch-conf now displays the new differences:

--- /etc/bash/bashrc    2005-08-11 22:29:36.000000000 +0200
+++ /etc/bash/._mrg0000_bashrc  2006-09-24 15:58:54.000000000 +0200

The user decides that they want to abandon the changes they made and go back to the original new file, so they select the t option. dispatch-conf will forget about ._mrg* and ._cfg* becomes considered as "new" again.

Once the user is happy with the changes, they select the u (use-new) option to update /etc/bash/bashrc. All the temporary files created are now removed and a backup of the changes is made to /etc/config-archive (either a full copy of the old file, or if the user has rcs installed and enabled as per this article, just the differences.

See also

Retrieved from ""

Last modified: Sun, 28 Sep 2008 06:58:00 +0000 Hits: 51,892