Dispatch-conf

From Gentoo Linux Wiki

[edit] Introduction

Dispatch-conf is a script designed to ease config file updates. 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.

[edit] Setup

No installation is necessary, it comes with portage so you already have it installed. It will work perfectly well "out of the box", but you can change the way it acts using the configuration file, which is located at /etc/dispatch-conf.conf.

[edit] 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 /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.

[edit] 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.

Then 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.

[edit] Use colordiff to view changes

Now change the diff line in the config file to: diff="colordiff -Nu '%s' '%s' | less --no-init --QUIT-AT-EOF -R"

[edit] 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: 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 :

• ]c : jump to next change
• [c : jump to previous change
• Ctrl-W <Right> or Ctrl-W <Left> : 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
• :diffupdate : causes vimdiff to re-scan the files for differences (sometimes it gets confused)

See also the Vim documentation for further help.

[edit] Use xxdiff to view and merge changes

Then alter the diff line and merge lines to match the following in the config file:

# xxdiff for viewing differences:
diff="xxdiff '%s' '%s'"

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

[edit] Usage

[edit] 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.

[edit] 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 /etc/portage/package.keywords.

• 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 merge the files (m merge)
• toggle between the two copies (t toggle-merge)
• look at the differences between the merged and pre-merged files (l look-merge)

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.

[edit] 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.

[edit] 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.