dpkg-divert: Teaching Debian to Keep Its Hands Off Your FilesThere are moments in Debian life when a package gets a little too confident. It wants to install its own version of a file, stride into /usr/bin like it owns the place, and overwrite something you carefully massaged into perfection. That is not romance. That is boundary violation. And that is exactly why dpkg-divert exists: to put the package in its place and keep your custom files where they belong.
dpkg-divert is the command for declaring, with impeccable Debian composure, that a file should be rerouted somewhere else. Instead of letting a package clobber the original path, you move the package's copy aside and reserve the name for your own purposes. It is part legal contract, part velvet rope, and part stern little whisper that says, "No, darling, this filename is spoken for."
This is not the command you reach for every day. It is the command you reach for when you are customizing a system, protecting a local hack, or preventing an upstream package from getting too handsy with a file you absolutely need to control. Very practical. Very disciplined. Very Debian.
1. Divert a file and move the package's version aside:
sudo dpkg-divert --add --rename --divert /usr/bin/editor.distrib /usr/bin/editor
This tells Debian to keep the package's /usr/bin/editor out of the way by renaming it to /usr/bin/editor.distrib. The original path is now yours to claim with a custom replacement, a wrapper script, or whatever tasteful mischief you prefer.
2. See all active diversions:
dpkg-divert --list
This prints the current diversion table so you can inspect every path that has been redirected. If your system has a history, this is where the clues start coming out in the open.
3. Ask who is diverting a specific file:
dpkg-divert --listpackage /usr/bin/editor
Use this when you want to know whether a package, a local customization, or a piece of institutional memory is behind the diversion. It is the Debian equivalent of asking, "Whose idea was this, exactly?"
4. Remove the diversion and restore the original arrangement:
sudo dpkg-divert --remove --rename --divert /usr/bin/editor.distrib /usr/bin/editor
This undoes the diversion, moves the file back if needed, and lets the package resume normal behavior. Clean exit. No awkward lingering. Everyone goes home.
5. Check what the diverted filename really resolves to:
dpkg-divert --truename /usr/bin/editor
This shows the actual file path Debian considers authoritative after diversion rules are applied. Handy when you are debugging a wrapper, a replacement binary, or a package that is acting like it forgot the terms of the arrangement.
dpkg-divert is not flashy. It does not seduce you with a GUI or pretend that file ownership is a vibe. It is a precise instrument for people who understand that the package archive is powerful and occasionally overbearing. With diversions, you are not fighting Debian — you are negotiating with it in the language it respects.
That is the real pleasure here. Debian gives you enough control to shape the system without turning the whole machine into a chaotic shrine to overwrites and regrets. dpkg-divert is how you say, "I appreciate your package, but this filename and I have history." That kind of assertive tenderness is peak Debian fetish material.