chiark - git - mdw - dpkg/blob - man/dpkg-divert.man

   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 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 .TH dpkg\-divert 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  22 .nh
  23 .SH NAME
  24 dpkg\-divert \- override a package's version of a file
  25 .
  26 .SH SYNOPSIS
  27 .B dpkg\-divert
  28 .RI [ option ...]
  29 .I command
  30 .
  31 .SH DESCRIPTION
  32 .B dpkg\-divert
  33 is the utility used to set up and update the list of diversions.
  34 .PP
  35 File \fIdiversions\fP are a way of forcing
  36 .BR dpkg (1)
  37 not to install a file into its
  38 location, but to a \fIdiverted\fP location. Diversions can be used through the
  39 Debian package scripts to move a file away when it causes a conflict. System
  40 administrators can also use it to override some package's configuration file,
  41 or whenever some files (which aren't marked as “conffiles”) need to be
  42 preserved by \fBdpkg\fP, when installing a newer version of a package which
  43 contains those files.
  44 .sp
  45 .SH COMMANDS
  46 .TP
  47 .RB [ \-\-add "] \fIfile\fP"
  48 Add a diversion for \fIfile\fP.
  49 .TP
  50 .BI \-\-remove " file"
  51 Remove a diversion for \fIfile\fP.
  52 .TP
  53 .BI \-\-list " glob-pattern"
  54 List diversions matching \fIglob-pattern\fP.
  55 .TP
  56 .BI \-\-listpackage " file"
  57 Print the name of the package that diverts \fIfile\fP (since dpkg 1.15.0).
  58 Prints LOCAL if
  59 \fIfile\fP is locally diverted and nothing if \fIfile\fP is not diverted.
  60 .TP
  61 .BI \-\-truename " file"
  62 Print the real name for a diverted file.
  63 .
  64 .SH OPTIONS
  65 .TP
  66 .BI \-\-admindir " directory"
  67 Set the \fBdpkg\fP data directory to \fIdirectory\fP (default:
  68 \fI%ADMINDIR%\fP).
  69 .TP
  70 .BI \-\-divert " divert-to"
  71 \fIdivert-to\fP is the location where the versions of \fIfile\fP, as
  72 provided by other packages, will be diverted.
  73 .TP
  74 .B \-\-local
  75 Specifies that all packages' versions of this file are diverted.
  76 This means, that there are no exceptions, and whatever package is installed,
  77 the file is diverted. This can be used by an admin to install a locally
  78 modified version.
  79 .TP
  80 .BI \-\-package " package"
  81 \fIpackage\fP is the name of a package whose copy of \fIfile\fP will not
  82 be diverted. i.e. \fIfile\fP will be diverted for all packages except
  83 \fIpackage\fP.
  84 .TP
  85 .B \-\-quiet
  86 Quiet mode, i.e. no verbose output.
  87 .TP
  88 .B \-\-rename
  89 Actually move the file aside (or back). \fBdpkg\-divert\fP will abort operation
  90 in case the destination file already exists.
  91 .TP
  92 .B \-\-test
  93 Test mode, i.e. don't actually perform any changes, just demonstrate.
  94 .TP
  95 .BR \-? ", " \-\-help
  96 Show the usage message and exit.
  97 .TP
  98 .B \-\-version
  99 Show the version and exit.
 100 .
 101 .SH EXIT STATUS
 102 .TP
 103 .B 0
 104 The requested action was successfully performed.
 105 .TP
 106 .B 2
 107 Fatal or unrecoverable error due to invalid command-line usage, or
 108 interactions with the system, such as accesses to the database,
 109 memory allocations, etc.
 110 .
 111 .SH ENVIRONMENT
 112 .TP
 113 .B DPKG_ADMINDIR
 114 If set and the \fB\-\-admindir\fP option has not been specified, it will
 115 be used as the \fBdpkg\fP data directory.
 116 .TP
 117 .B DPKG_MAINTSCRIPT_PACKAGE
 118 If set and the \fB\-\-local\fP and \fB\-\-package\fP options have not been
 119 specified, \fBdpkg\-divert\fP will use it as the package name.
 120 .
 121 .SH FILES
 122 .TP
 123 .I %ADMINDIR%/diversions
 124 File which contains the current list of diversions of the system. It is
 125 located in the \fBdpkg\fP administration directory, along with other files
 126 important to \fBdpkg\fP, such as \fIstatus\fP or \fIavailable\fP.
 127 .br
 128 Note: \fBdpkg\-divert\fP preserves the old copy of this file, with extension
 129 \fI\-old\fP, before replacing it with the new one.
 130 .
 131 .SH NOTES
 132 When adding, default is \fB\-\-local\fP and \fB\-\-divert\fP
 133 \fIoriginal\fP\fB.distrib\fP. When removing, \fB\-\-package\fP or
 134 \fB\-\-local\fP and \fB\-\-divert\fP must match if specified.
 135
 136 Directories can't be diverted with \fBdpkg\-divert\fP.
 137
 138 Care should be taken when diverting shared libraries, \fBldconfig\fP(8)
 139 creates a symbolic link based on the DT_SONAME field embedded in the library.
 140 Because \fBldconfig\fP doesn't honour diverts (only \fBdpkg\fP does),
 141 the symlink may end up pointing at the diverted library, if a diverted
 142 library has the same SONAME as the undiverted one.
 143 .
 144 .SH EXAMPLES
 145 To divert all copies of a \fI/usr/bin/example\fR to \fI/usr/bin/example.foo\fR,
 146 i.e. directs all packages providing \fI/usr/bin/example\fR to install it as
 147 \fI/usr/bin/example.foo\fR, performing the rename if required:
 148 .HP
 149 dpkg\-divert \-\-divert /usr/bin/example.foo \-\-rename /usr/bin/example
 150 .PP
 151 To remove that diversion:
 152 .HP
 153 dpkg\-divert \-\-rename \-\-remove /usr/bin/example
 154
 155 .PP
 156 To divert any package trying to install \fI/usr/bin/example\fR to
 157 \fI/usr/bin/example.foo\fR, except your own \fIwibble\fR package:
 158 .HP
 159 dpkg\-divert \-\-package wibble \-\-divert /usr/bin/example.foo \-\-rename /usr/bin/example
 160 .PP
 161 To remove that diversion:
 162 .HP
 163 dpkg\-divert \-\-package wibble \-\-rename \-\-remove /usr/bin/example
 164 .
 165 .SH SEE ALSO
 166 .BR dpkg (1).