man/dpkg-divert.pod

   1 # dpkg manual page - dpkg-divert(1)
   2 #
   3 # Copyright © 1995 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 1999 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2004 Scott James Remnant <keybuk@debian.org>
   6 # Copyright © 2007-2013, 2015-2018 Guillem Jover <guillem@debian.org>
   7 #
   8 # This is free software; you can redistribute it and/or modify
   9 # it under the terms of the GNU General Public License as published by
  10 # the Free Software Foundation; either version 2 of the License, or
  11 # (at your option) any later version.
  12 #
  13 # This is distributed in the hope that it will be useful,
  14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 # GNU General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  20
  21 =encoding utf8
  22
  23 =head1 NAME
  24
  25 dpkg-divert - override a package's version of a file
  26
  27 =head1 SYNOPSIS
  28
  29 B<dpkg-divert>
  30 [I<option>...]
  31 I<command>
  32
  33 =head1 DESCRIPTION
  34
  35 B<dpkg-divert>
  36 is the utility used to set up and update the list of diversions.
  37
  38 File I<diversions> are a way of forcing
  39 B<dpkg>(1)
  40 not to install a file into its
  41 location, but to a I<diverted> location. Diversions can be used through the
  42 Debian package scripts to move a file away when it causes a conflict. System
  43 administrators can also use it to override some package's configuration file,
  44 or whenever some files (which aren't marked as “conffiles”) need to be
  45 preserved by B<dpkg>, when installing a newer version of a package which
  46 contains those files.
  47
  48 =head1 COMMANDS
  49
  50 =over
  51
  52 =item [B<--add>] I<file>
  53
  54 Add a diversion for I<file>.
  55 The file is currently not renamed, see B<--rename>.
  56
  57 =item B<--remove> I<file>
  58
  59 Remove a diversion for I<file>.
  60 The file is currently not renamed, see B<--rename>.
  61
  62 =item B<--list> [I<glob-pattern>]
  63
  64 List all diversions, or ones matching I<glob-pattern>.
  65
  66 =item B<--listpackage> I<file>
  67
  68 Print the name of the package that diverts I<file> (since dpkg 1.15.0).
  69 Prints LOCAL if
  70 I<file> is locally diverted and nothing if I<file> is not diverted.
  71
  72 =item B<--truename> I<file>
  73
  74 Print the real name for a diverted file.
  75
  76 =back
  77
  78 =head1 OPTIONS
  79
  80 =over
  81
  82 =item B<--admindir> I<directory>
  83
  84 Set the administrative directory to I<directory>.
  85 Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set.
  86
  87 =item B<--instdir> I<directory>
  88
  89 Set the installation directory, which refers to the directory where
  90 packages get installed (since dpkg 1.19.2).
  91 Defaults to «I</>» if B<DPKG_ROOT> has not been set.
  92
  93 =item B<--root> I<directory>
  94
  95 Set the root directory to B<directory>, which sets the installation
  96 directory to «I<directory>» and the administrative
  97 directory to «I<directory>B<%ADMINDIR%>» (since dpkg 1.19.2)
  98 if B<DPKG_ROOT> has not been set.
  99
 100 =item B<--divert> I<divert-to>
 101
 102 I<divert-to> is the location where the versions of I<file>, as
 103 provided by other packages, will be diverted.
 104
 105 =item B<--local>
 106
 107 Specifies that all packages' versions of this file are diverted.
 108 This means, that there are no exceptions, and whatever package is installed,
 109 the file is diverted. This can be used by an admin to install a locally
 110 modified version.
 111
 112 =item B<--package> I<package>
 113
 114 I<package> is the name of a package whose copy of I<file> will not
 115 be diverted. i.e. I<file> will be diverted for all packages except
 116 I<package>.
 117
 118 =item B<--quiet>
 119
 120 Quiet mode, i.e. no verbose output.
 121
 122 =item B<--rename>
 123
 124 Actually move the file aside (or back). B<dpkg-divert> will abort operation
 125 in case the destination file already exists.
 126 This is the common behavior used for diversions of files from the
 127 non-B<Essential> package set (see B<--no-rename> for more details).
 128
 129 =item B<--no-rename>
 130
 131 Specifies that the file should not be renamed while adding or removing the
 132 diversion into the database (since dpkg 1.19.1).
 133 This is intended for diversions of files from the B<Essential> package set,
 134 where the temporary disappearance of the original file is not acceptable, as
 135 it can render the system non-functional.
 136 This is the default behavior, but that will change in the dpkg 1.20.x cycle.
 137
 138 =item B<--test>
 139
 140 Test mode, i.e. don't actually perform any changes, just demonstrate.
 141
 142 =item B<-?>, B<--help>
 143
 144 Show the usage message and exit.
 145
 146 =item B<--version>
 147
 148 Show the version and exit.
 149
 150 =back
 151
 152 =head1 EXIT STATUS
 153
 154 =over
 155
 156 =item B<0>
 157
 158 The requested action was successfully performed.
 159
 160 =item B<2>
 161
 162 Fatal or unrecoverable error due to invalid command-line usage, or
 163 interactions with the system, such as accesses to the database,
 164 memory allocations, etc.
 165
 166 =back
 167
 168 =head1 ENVIRONMENT
 169
 170 =over
 171
 172 =item B<DPKG_ROOT>
 173
 174 If set and the B<--instdir> or B<--root> options have not been
 175 specified, it will be used as the filesystem root directory
 176 (since dpkg 1.19.2).
 177
 178 =item B<DPKG_ADMINDIR>
 179
 180 If set and the B<--admindir> or B<--root> options have not been
 181 specified, it will be used as the B<dpkg> data directory.
 182
 183 =item B<DPKG_MAINTSCRIPT_PACKAGE>
 184
 185 If set and the B<--local> and B<--package> options have not been
 186 specified, B<dpkg-divert> will use it as the package name.
 187
 188 =item B<DPKG_DEBUG>
 189
 190 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 191 The currently accepted flags are described in the B<dpkg --debug> option,
 192 but not all these flags might have an effect on this program.
 193
 194 =item B<DPKG_COLORS>
 195
 196 Sets the color mode (since dpkg 1.18.5).
 197 The currently accepted values are: B<auto> (default), B<always> and
 198 B<never>.
 199
 200 =back
 201
 202 =head1 FILES
 203
 204 =over
 205
 206 =item I<%ADMINDIR%/diversions>
 207
 208 File which contains the current list of diversions of the system. It is
 209 located in the B<dpkg> administration directory, along with other files
 210 important to B<dpkg>, such as I<status> or I<available>.
 211
 212 B<Note>: B<dpkg-divert> preserves the old copy of this file, with extension
 213 I<-old>, before replacing it with the new one.
 214
 215 =back
 216
 217 =head1 NOTES
 218
 219 When adding, default is B<--local> and B<--divert>
 220 I<original>B<.distrib>. When removing, B<--package> or
 221 B<--local> and B<--divert> must match if specified.
 222
 223 Directories can't be diverted with B<dpkg-divert>.
 224
 225 Care should be taken when diverting shared libraries, B<ldconfig>(8)
 226 creates a symbolic link based on the DT_SONAME field embedded in the library.
 227 Because B<ldconfig> does not honor diverts (only B<dpkg> does),
 228 the symlink may end up pointing at the diverted library, if a diverted
 229 library has the same SONAME as the undiverted one.
 230
 231 =head1 EXAMPLES
 232
 233 To divert all copies of a I</usr/bin/example> to I</usr/bin/example.foo>,
 234 i.e. directs all packages providing I</usr/bin/example> to install it as
 235 I</usr/bin/example.foo>, performing the rename if required:
 236
 237  dpkg-divert --divert /usr/bin/example.foo --rename /usr/bin/example
 238
 239 To remove that diversion:
 240
 241  dpkg-divert --rename --remove /usr/bin/example
 242
 243 To divert any package trying to install I</usr/bin/example> to
 244 I</usr/bin/example.foo>, except your own I<wibble> package:
 245
 246  dpkg-divert --package wibble --divert /usr/bin/example.foo \
 247     --rename /usr/bin/example
 248
 249 To remove that diversion:
 250
 251  dpkg-divert --package wibble --rename --remove /usr/bin/example
 252
 253 =head1 SEE ALSO
 254
 255 B<dpkg>(1).