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 L<dpkg(1)>
  40 not to install a file into its
  41 location, but to a I<diverted> location.
  42 Diversions can be used through the package maintainer scripts to move a file
  43 away when it causes a conflict.
  44 System
  45 administrators can also use it to override some package's configuration file,
  46 or whenever some files (which aren't marked as “conffiles”) need to be
  47 preserved by B<dpkg>, when installing a newer version of a package which
  48 contains those files.
  49
  50 =head1 COMMANDS
  51
  52 =over
  53
  54 =item [B<--add>] I<file>
  55
  56 Add a diversion for I<file>.
  57 The file is currently not renamed, see B<--rename>.
  58
  59 =item B<--remove> I<file>
  60
  61 Remove a diversion for I<file>.
  62 The file is currently not renamed, see B<--rename>.
  63
  64 =item B<--list> [I<glob-pattern>]
  65
  66 List all diversions, or ones matching I<glob-pattern>.
  67
  68 =item B<--listpackage> I<file>
  69
  70 Print the name of the package that diverts I<file> (since dpkg 1.15.0).
  71 Prints LOCAL if
  72 I<file> is locally diverted and nothing if I<file> is not diverted.
  73
  74 =item B<--truename> I<file>
  75
  76 Print the real name for a diverted file.
  77
  78 =back
  79
  80 =head1 OPTIONS
  81
  82 =over
  83
  84 =item B<--admindir> I<directory>
  85
  86 Set the administrative directory to I<directory>.
  87 Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set.
  88
  89 =item B<--instdir> I<directory>
  90
  91 Set the installation directory, which refers to the directory where
  92 packages get installed (since dpkg 1.19.2).
  93 Defaults to «I</>» if B<DPKG_ROOT> has not been set.
  94
  95 =item B<--root> I<directory>
  96
  97 Set the root directory to B<directory>, which sets the installation
  98 directory to «I<directory>» and the administrative
  99 directory to «I<directory>B<%ADMINDIR%>» (since dpkg 1.19.2)
 100 if B<DPKG_ROOT> has not been set.
 101
 102 =item B<--divert> I<divert-to>
 103
 104 I<divert-to> is the location where the versions of I<file>, as
 105 provided by other packages, will be diverted.
 106
 107 =item B<--local>
 108
 109 Specifies that all packages' versions of this file are diverted.
 110 This means, that there are no exceptions, and whatever package is installed,
 111 the file is diverted.
 112 This can be used by an admin to install a locally
 113 modified version.
 114
 115 =item B<--package> I<package>
 116
 117 I<package> is the name of a package whose copy of I<file> will not
 118 be diverted.
 119 i.e. I<file> will be diverted for all packages except
 120 I<package>.
 121
 122 =item B<--quiet>
 123
 124 Quiet mode, i.e. no verbose output.
 125
 126 =item B<--rename>
 127
 128 Actually move the file aside (or back).
 129 B<dpkg-divert> will abort operation
 130 in case the destination file already exists.
 131 This is the common behavior used for diversions of files from the
 132 non-B<Essential> package set (see B<--no-rename> for more details).
 133
 134 =item B<--no-rename>
 135
 136 Specifies that the file should not be renamed while adding or removing the
 137 diversion into the database (since dpkg 1.19.1).
 138 This is intended for diversions of files from the B<Essential> package set,
 139 where the temporary disappearance of the original file is not acceptable, as
 140 it can render the system non-functional.
 141 This is the default behavior, but that will change in the dpkg 1.20.x cycle.
 142
 143 =item B<--test>
 144
 145 Test mode, i.e. don't actually perform any changes, just demonstrate.
 146
 147 =item B<-?>, B<--help>
 148
 149 Show the usage message and exit.
 150
 151 =item B<--version>
 152
 153 Show the version and exit.
 154
 155 =back
 156
 157 =head1 EXIT STATUS
 158
 159 =over
 160
 161 =item B<0>
 162
 163 The requested action was successfully performed.
 164
 165 =item B<2>
 166
 167 Fatal or unrecoverable error due to invalid command-line usage, or
 168 interactions with the system, such as accesses to the database,
 169 memory allocations, etc.
 170
 171 =back
 172
 173 =head1 ENVIRONMENT
 174
 175 =over
 176
 177 =item B<DPKG_ROOT>
 178
 179 If set and the B<--instdir> or B<--root> options have not been
 180 specified, it will be used as the filesystem root directory
 181 (since dpkg 1.19.2).
 182
 183 =item B<DPKG_ADMINDIR>
 184
 185 If set and the B<--admindir> or B<--root> options have not been
 186 specified, it will be used as the B<dpkg> data directory.
 187
 188 =item B<DPKG_MAINTSCRIPT_PACKAGE>
 189
 190 If set and the B<--local> and B<--package> options have not been
 191 specified, B<dpkg-divert> will use it as the package name.
 192
 193 =item B<DPKG_DEBUG>
 194
 195 Sets the debug mask (since dpkg 1.21.10) from an octal value.
 196 The currently accepted flags are described in the B<dpkg --debug> option,
 197 but not all these flags might have an effect on this program.
 198
 199 =item B<DPKG_COLORS>
 200
 201 Sets the color mode (since dpkg 1.18.5).
 202 The currently accepted values are: B<auto> (default), B<always> and
 203 B<never>.
 204
 205 =item B<DPKG_NLS>
 206
 207 If set, it will be used to decide whether to activate Native Language Support,
 208 also known as internationalization (or i18n) support (since dpkg 1.22.7).
 209 The accepted values are: B<0> and B<1> (default).
 210
 211 =back
 212
 213 =head1 FILES
 214
 215 =over
 216
 217 =item I<%ADMINDIR%/diversions>
 218
 219 File which contains the current list of diversions of the system.
 220 It is
 221 located in the B<dpkg> administration directory, along with other files
 222 important to B<dpkg>, such as I<status> or I<available>.
 223
 224 B<Note>: B<dpkg-divert> preserves the old copy of this file, with extension
 225 I<-old>, before replacing it with the new one.
 226
 227 =back
 228
 229 =head1 NOTES
 230
 231 When adding, default is B<--local> and B<--divert>
 232 I<original>B<.distrib>.
 233 When removing, B<--package> or
 234 B<--local> and B<--divert> must match if specified.
 235
 236 Directories can't be diverted with B<dpkg-divert>.
 237
 238 Care should be taken when diverting shared libraries, L<ldconfig(8)>
 239 creates a symbolic link based on the DT_SONAME field embedded in the library.
 240 Because B<ldconfig> does not honor diverts (only B<dpkg> does),
 241 the symlink may end up pointing at the diverted library, if a diverted
 242 library has the same SONAME as the undiverted one.
 243
 244 =head1 EXAMPLES
 245
 246 To divert all copies of a I</usr/bin/example> to I</usr/bin/example.foo>,
 247 i.e. directs all packages providing I</usr/bin/example> to install it as
 248 I</usr/bin/example.foo>, performing the rename if required:
 249
 250  dpkg-divert --divert /usr/bin/example.foo --rename /usr/bin/example
 251
 252 To remove that diversion:
 253
 254  dpkg-divert --rename --remove /usr/bin/example
 255
 256 To divert any package trying to install I</usr/bin/example> to
 257 I</usr/bin/example.foo>, except your own I<wibble> package:
 258
 259  dpkg-divert --package wibble --divert /usr/bin/example.foo \
 260     --rename /usr/bin/example
 261
 262 To remove that diversion:
 263
 264  dpkg-divert --package wibble --rename --remove /usr/bin/example
 265
 266 =head1 SEE ALSO
 267
 268 L<dpkg(1)>.