summaryrefslogtreecommitdiffstats
path: root/man/dpkg-divert.pod
diff options
context:
space:
mode:
Diffstat (limited to 'man/dpkg-divert.pod')
-rw-r--r--man/dpkg-divert.pod262
1 files changed, 262 insertions, 0 deletions
diff --git a/man/dpkg-divert.pod b/man/dpkg-divert.pod
new file mode 100644
index 0000000..3985657
--- /dev/null
+++ b/man/dpkg-divert.pod
@@ -0,0 +1,262 @@
+# dpkg manual page - dpkg-divert(1)
+#
+# Copyright © 1995 Ian Jackson <ijackson@chiark.greenend.org.uk>
+# Copyright © 1999 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2004 Scott James Remnant <keybuk@debian.org>
+# Copyright © 2007-2013, 2015-2018 Guillem Jover <guillem@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-divert - override a package's version of a file
+
+=head1 SYNOPSIS
+
+B<dpkg-divert>
+[I<option>...]
+I<command>
+
+=head1 DESCRIPTION
+
+B<dpkg-divert>
+is the utility used to set up and update the list of diversions.
+
+File I<diversions> are a way of forcing
+L<dpkg(1)>
+not to install a file into its
+location, but to a I<diverted> location.
+Diversions can be used through the package maintainer scripts to move a file
+away when it causes a conflict.
+System
+administrators can also use it to override some package's configuration file,
+or whenever some files (which aren't marked as “conffiles”) need to be
+preserved by B<dpkg>, when installing a newer version of a package which
+contains those files.
+
+=head1 COMMANDS
+
+=over
+
+=item [B<--add>] I<file>
+
+Add a diversion for I<file>.
+The file is currently not renamed, see B<--rename>.
+
+=item B<--remove> I<file>
+
+Remove a diversion for I<file>.
+The file is currently not renamed, see B<--rename>.
+
+=item B<--list> [I<glob-pattern>]
+
+List all diversions, or ones matching I<glob-pattern>.
+
+=item B<--listpackage> I<file>
+
+Print the name of the package that diverts I<file> (since dpkg 1.15.0).
+Prints LOCAL if
+I<file> is locally diverted and nothing if I<file> is not diverted.
+
+=item B<--truename> I<file>
+
+Print the real name for a diverted file.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<--admindir> I<directory>
+
+Set the administrative directory to I<directory>.
+Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set.
+
+=item B<--instdir> I<directory>
+
+Set the installation directory, which refers to the directory where
+packages get installed (since dpkg 1.19.2).
+Defaults to «I</>» if B<DPKG_ROOT> has not been set.
+
+=item B<--root> I<directory>
+
+Set the root directory to B<directory>, which sets the installation
+directory to «I<directory>» and the administrative
+directory to «I<directory>B<%ADMINDIR%>» (since dpkg 1.19.2)
+if B<DPKG_ROOT> has not been set.
+
+=item B<--divert> I<divert-to>
+
+I<divert-to> is the location where the versions of I<file>, as
+provided by other packages, will be diverted.
+
+=item B<--local>
+
+Specifies that all packages' versions of this file are diverted.
+This means, that there are no exceptions, and whatever package is installed,
+the file is diverted.
+This can be used by an admin to install a locally
+modified version.
+
+=item B<--package> I<package>
+
+I<package> is the name of a package whose copy of I<file> will not
+be diverted.
+i.e. I<file> will be diverted for all packages except
+I<package>.
+
+=item B<--quiet>
+
+Quiet mode, i.e. no verbose output.
+
+=item B<--rename>
+
+Actually move the file aside (or back).
+B<dpkg-divert> will abort operation
+in case the destination file already exists.
+This is the common behavior used for diversions of files from the
+non-B<Essential> package set (see B<--no-rename> for more details).
+
+=item B<--no-rename>
+
+Specifies that the file should not be renamed while adding or removing the
+diversion into the database (since dpkg 1.19.1).
+This is intended for diversions of files from the B<Essential> package set,
+where the temporary disappearance of the original file is not acceptable, as
+it can render the system non-functional.
+This is the default behavior, but that will change in the dpkg 1.20.x cycle.
+
+=item B<--test>
+
+Test mode, i.e. don't actually perform any changes, just demonstrate.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+The requested action was successfully performed.
+
+=item B<2>
+
+Fatal or unrecoverable error due to invalid command-line usage, or
+interactions with the system, such as accesses to the database,
+memory allocations, etc.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<DPKG_ROOT>
+
+If set and the B<--instdir> or B<--root> options have not been
+specified, it will be used as the filesystem root directory
+(since dpkg 1.19.2).
+
+=item B<DPKG_ADMINDIR>
+
+If set and the B<--admindir> or B<--root> options have not been
+specified, it will be used as the B<dpkg> data directory.
+
+=item B<DPKG_MAINTSCRIPT_PACKAGE>
+
+If set and the B<--local> and B<--package> options have not been
+specified, B<dpkg-divert> will use it as the package name.
+
+=item B<DPKG_DEBUG>
+
+Sets the debug mask (since dpkg 1.21.10) from an octal value.
+The currently accepted flags are described in the B<dpkg --debug> option,
+but not all these flags might have an effect on this program.
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=back
+
+=head1 FILES
+
+=over
+
+=item I<%ADMINDIR%/diversions>
+
+File which contains the current list of diversions of the system.
+It is
+located in the B<dpkg> administration directory, along with other files
+important to B<dpkg>, such as I<status> or I<available>.
+
+B<Note>: B<dpkg-divert> preserves the old copy of this file, with extension
+I<-old>, before replacing it with the new one.
+
+=back
+
+=head1 NOTES
+
+When adding, default is B<--local> and B<--divert>
+I<original>B<.distrib>.
+When removing, B<--package> or
+B<--local> and B<--divert> must match if specified.
+
+Directories can't be diverted with B<dpkg-divert>.
+
+Care should be taken when diverting shared libraries, L<ldconfig(8)>
+creates a symbolic link based on the DT_SONAME field embedded in the library.
+Because B<ldconfig> does not honor diverts (only B<dpkg> does),
+the symlink may end up pointing at the diverted library, if a diverted
+library has the same SONAME as the undiverted one.
+
+=head1 EXAMPLES
+
+To divert all copies of a I</usr/bin/example> to I</usr/bin/example.foo>,
+i.e. directs all packages providing I</usr/bin/example> to install it as
+I</usr/bin/example.foo>, performing the rename if required:
+
+ dpkg-divert --divert /usr/bin/example.foo --rename /usr/bin/example
+
+To remove that diversion:
+
+ dpkg-divert --rename --remove /usr/bin/example
+
+To divert any package trying to install I</usr/bin/example> to
+I</usr/bin/example.foo>, except your own I<wibble> package:
+
+ dpkg-divert --package wibble --divert /usr/bin/example.foo \
+ --rename /usr/bin/example
+
+To remove that diversion:
+
+ dpkg-divert --package wibble --rename --remove /usr/bin/example
+
+=head1 SEE ALSO
+
+L<dpkg(1)>.