Dispatch-conf

Introduction
Dispatch-conf is a tool to update config files, mostly ones. Features are:
 * It can automatically update easy cases, like comment-only changes, or that haven't been changed by you between package upgradings.
 * It creates backups and has more advanced options, unlike etc-update.

For more do and read the Configuration Files section. It's self-describing.

Setup
No installation is necessary. (It's included in portage.) It works well out-of-the-box, but you can edit the configuration file.

Backup Directory
dispatch-conf keeps copies of changed files in a directory specified in the config files. This is controlled by the archive-dir value. By default this is.

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: Then set in.

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

Usage
Just run 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 ), 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.

Manually Merging
If there are files that can't be auto merged, you will see an output like this, if using the default configuration: --- /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:

In the above example the file being updated is.
 * The first 2 lines are the file names of the new and old files. The line starting with +++ is the new filename and the line starting with --- is the old filename.
 * Lines beginning with @@ denote a snippet of a file. In the above, @@ -7,4 means that this snippet starts at line 7 of the original file and is 4 lines in length. Likewise, +7,4 @@ means that this same snippet starts at line 7 of the new file and is 4 lines in length.
 * Within a snippet, lines beginning with - or + belong only to the original or new file respectively.

At this point you can:
 * skip making a decision for now (n next)
 * open the new file with the editor defined by the EDITOR env variable (e edit-new)
 * delete the new file and use the old file (z zap-new)
 * use the new file and archive the old (u use-new)
 * manually edit how these files are merged (m merge). After merging, you sometimes want to:
 * toggle between the two copies (t toggle-merge)
 * look at the differences between the merged and pre-merged files (l look-merge)

Merge relies on "sdiff". (It's an old tool and not so easy to use, and you may want to use alternatives, as explained in sections below.) sdiff 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.

Details of intermediate steps
A user is merging the system package set, new file appears and the user needs update it into their. 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, 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 and  becomes considered as "new" again.

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

Testing
After you setup some external tools, you can test them by putting two similar files as and.

Use colordiff to view changes
Colordiff puts color on different lines. (But not word-wise.) Install colordiff with:

Now change the diff line in the config file to:

Use (g)vimdiff to merge changes
You can also use vimdiff (for gvimdiff use -f flag) to merge changes. To do this, modify the configuration file by changing the merge line:

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 :
 * : jump to next change
 * : jump to previous change
 * or : go to the other window
 * (diff obtain): get the text of the highlighted block from the other window
 * (diff put) : put the text of the highlighted block to the other window
 * : open fold under the cursor
 * : close fold under the cursor
 * : open all folds
 * : write and exit
 * : causes vimdiff to re-scan the files for differences (sometimes it gets confused)

See also the Vim documentation for further help.

Use xxdiff to view and merge changes
xxdiff is a diff with qt GUI. You can install xxdiff with: Then alter the diff line and merge lines to match the following in the config file:

Using "git add -p" for merging
"git add -p" is a nice tool to merge, even if you've never used git; the help is always available, and easy to understand, while sdiff's help is quite opaque. (Strictly speaking, "git add" only puts hunks in the index, bun you understand what I mean, right?)

First, prepare a script:

Then edit the configuration file:

Alternatives

 * sys-apps/etckeeper
 * app-portage/cfg-update
 * app-portage/conf-update
 * app-portage/etc-proposals: Development stopped since 2008