dpkg-divert

dpkg-divert [option...] {command}

Commands:
--add file [--local] [--divert divert-file]
--remove file
--list [file]
--rename old-file new-file

file
    The absolute path to the file that is to be diverted, removed, or listed.

--add
    Adds a new diversion for the specified file. If --divert is not used, the file will be diverted to file.diverted in the same directory.

--remove
    Removes an existing diversion for the specified file from the dpkg database.

--list
    Lists all currently active diversions, or only those for the specified file if provided.

--rename
    Renames an existing diversion entry from old-file to new-file in the dpkg database and renames the physical diverted file if it exists.

--local
    Used with --add, marks the diversion as 'local'. This means dpkg will not be aware of the original path, treating the diverted path as the only one it knows for the package's file.

--divert divert-file
    Used with --add, explicitly specifies the full path to which the file should be diverted. If omitted, the default is to append '.diverted' to the original filename.

--no-act
    Perform a dry run. Show what actions would be taken without actually making any changes to the system or dpkg database.

--quiet
    Suppresses informational output, showing only errors or warnings.

The dpkg-divert command allows a system administrator to override the default location where files are installed by dpkg, the Debian package manager. This is particularly useful for maintaining local versions of files, such as configuration files or binaries, that would otherwise be overwritten by package installations or upgrades. By diverting a file, dpkg-divert instructs dpkg to install the package's version of that file to a different, specified path, leaving the original file at its intended location untouched. It records these diversions in the dpkg status database, ensuring that future package operations respect the diversion. This mechanism helps prevent conflicts and data loss for customized system components, offering flexibility in system configuration management.

Manual File Movement: When adding a diversion for an existing file, dpkg-divert only registers the diversion; you must manually move the existing file to its new diverted path (e.g., from /usr/bin/foo to /usr/bin/foo.diverted). Similarly, removing a diversion does not move the file back.

Critical Files: Exercise extreme caution when diverting critical system files or binaries, as incorrect usage can lead to system instability or breakage.

Global vs. Local: Understand the implications of --local diversions. A 'global' diversion (default) tells dpkg to install to the new path and consider the original path as 'owned' by the system. A 'local' diversion means dpkg will install to the new path, leaving the original path entirely unmanaged by dpkg and free for local use without conflicts.

Consider a scenario where you have a customized /etc/bash.bashrc file and wish to prevent a package update from overwriting it:

1. Add a diversion:
sudo dpkg-divert --local --add /etc/bash.bashrc
This command registers a diversion for /etc/bash.bashrc. The package's version will now be installed at /etc/bash.bashrc.diverted. You must then manually move your existing customized file to /etc/bash.bashrc (if it was already there) or keep it at the original location while the package version goes to the diverted path.

2. List diversions:
dpkg-divert --list /etc/bash.bashrc
This will show the active diversion for /etc/bash.bashrc.

3. Remove the diversion:
sudo dpkg-divert --remove /etc/bash.bashrc
This removes the diversion entry from the dpkg database. Note that the diverted file (e.g., /etc/bash.bashrc.diverted) is not automatically moved back to its original path by this command.

dpkg-divert is an integral part of the dpkg suite, which has been the foundational package management system for Debian-based distributions since the mid-1990s. The concept of file diversion was introduced early in dpkg's development to address the need for system administrators to maintain local modifications or alternative versions of files that are also managed by packages, preventing overwrites during upgrades. Its core functionality has remained consistent, evolving primarily through minor enhancements and integration within the broader dpkg ecosystem.

dpkg(8), update-alternatives(8)