docs/manpages/rm.1.sgml

   1 <!-- -*- mode: sgml; mode: fold -*- -->
   2 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   3
   4 <!ENTITY % dakent SYSTEM "dak.ent">
   5 %dakent;
   6
   7 ]>
   8
   9 <refentry>
  10   &dak-docinfo;
  11
  12   <refmeta>
  13     <refentrytitle>dak_rm</>
  14     <manvolnum>1</>
  15   </refmeta>
  16
  17   <!-- Man page title -->
  18   <refnamediv>
  19     <refname>dak rm</>
  20     <refpurpose>Utility to remove/add packages from suites</>
  21   </refnamediv>
  22
  23   <!-- Arguments -->
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>dak rm</>
  27       <arg><option><replaceable>options</replaceable></></arg>
  28       <arg choice="plain"><replaceable>package</replaceable></arg>
  29       <arg><option><replaceable>...</replaceable></option></arg>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <RefSect1><Title>Description</>
  34     <para>
  35       <command>dak rm</command> is the command line tool to add and remove package sets from suites with enforced logging, optional bug closing and override updates.
  36     </PARA>
  37   </REFSECT1>
  38
  39   <RefSect1><Title>Options</>
  40
  41     <VariableList>
  42       <VarListEntry><term><option>-a/--architecture=<replaceable>architecture</replaceable></option></>
  43         <ListItem>
  44           <Para>Restrict the packages being considered to the architecture(s) listed.</PARA>
  45         </LISTITEM>
  46       </VarListEntry>
  47
  48       <VarListEntry><term><option>-b/--binary</option></>
  49         <ListItem>
  50           <Para>Only look at binary packages.</PARA>
  51         </LISTITEM>
  52       </VarListEntry>
  53
  54       <VarListEntry><term><option>-c/--component=<replaceable>component</replaceable></option></>
  55         <ListItem>
  56           <Para>Restrict the packages being considered to those found in the component(s) listed.  The default is <literal>main</literal>.</PARA>
  57         </LISTITEM>
  58       </VarListEntry>
  59
  60       <VarListEntry><term><option>-C/--carbon-copy=<replaceable>[ bug number | 'package' | email address ]</replaceable></option></>
  61         <ListItem>
  62           <Para>Carbon copy the bug closing mail to the address(es) given.  If the removal was not requested by the maintainer, this option should always be used to inform the maintainer of the package's removal.  3 types of address are accepted.</PARA>
  63             <itemizedlist>
  64               <listitem>
  65                 <para>number - assumed to be a bug number, and expanded to nnnnn@bugs.debian.org.</para>
  66               </listitem>
  67               <listitem>
  68                 <para>'<literal>package</literal>' - carbon copy package@package.debian.org for each package given as an argument.</para>
  69               </listitem>
  70               <listitem>
  71                 <para>anything containing '@' - assumed to be an email address, and carbon copied as is.</para>
  72               </listitem>
  73             </itemizedlist>
  74         </LISTITEM>
  75       </VarListEntry>
  76
  77       <VarListEntry><term><option>-d/--done=<replaceable>done</replaceable></option></>
  78         <ListItem>
  79           <Para>Close the bug(s) listed on successful completion.</PARA>
  80         </LISTITEM>
  81       </VarListEntry>
  82
  83       <VarListEntry><term><option>-m/--reason=<replaceable>reason</replaceable></option></>
  84         <ListItem>
  85           <Para>The reason for the removal or addition of the package(s).  This is a required option; if not provided an editor will be spawned so the reason can be added there.</PARA>
  86         </LISTITEM>
  87       </VarListEntry>
  88
  89       <VarListEntry><term><option>-n/--no-action</option></>
  90         <ListItem>
  91           <Para>Don't actually do anything; just show what would be done.</PARA>
  92         </LISTITEM>
  93       </VarListEntry>
  94
  95       <VarListEntry><term><option>-p/--partial</option></>
  96         <ListItem>
  97           <Para>Partial removal of a package, so the package is not removed from the overrides.  This option is implied by <option>-a/--architecture</option>.</PARA>
  98         </LISTITEM>
  99       </VarListEntry>
 100
 101       <VarListEntry><term><option>-R/--rdep-check</option></>
 102         <ListItem>
 103           <Para>Check the reverse dependencies (and build-dependencies) of the packages that are to be removed and warn if anything will break.</PARA>
 104         </LISTITEM>
 105       </VarListEntry>
 106
 107       <VarListEntry><term><option>-s/--suite=<replaceable>suite</replaceable></option></>
 108         <ListItem>
 109           <Para>Only add/remove the packages from the suite(s) listed.  The default is <literal>unstable</literal></PARA>
 110         </LISTITEM>
 111       </VarListEntry>
 112
 113       <VarListEntry><term><option>-S/--source-only</option></>
 114         <ListItem>
 115           <Para>Only look at source packages.</PARA>
 116         </LISTITEM>
 117       </VarListEntry>
 118
 119     </VariableList>
 120   </RefSect1>
 121
 122     <refsect1>
 123       <title>How packages are chosen</title>
 124       <para>There are 3 methods for selecting packages.</para>
 125       <itemizedlist>
 126         <listitem>
 127           <para>Source + Binaries. (default)</para>
 128           <para>In this mode <command>dak rm</command> will assume each of the package(s) passed as arguments are source packages and will also remove any binary packages built from these source packages.</para>
 129         </listitem>
 130         <listitem>
 131           <para>Binary only.</para>
 132           <para>Only binary packages are searched; source packages are ignored.  This mode is chosen by use of the <option>-b/--binary</option> switch.</para>
 133           <para>This should <emphasis>only</emphasis> be used for orphaned binary packages (i.e. those no longer built by source packages); otherwise, in any system (e.g. Debian) which has auto-building, pointless (and uninstallable) recompiles will be triggered.</para>
 134         </listitem>
 135         <listitem>
 136           <para>Source only.</para>
 137           <para>Only source packages are searched; binary packages are ignored.  This mode is chosen by use of the <option>-S/--source</option> switch.</para>
 138         </listitem>
 139       </itemizedlist>
 140     </refsect1>
 141
 142     <refsect1>
 143       <title>Configuration</title>
 144       <para><command>dak rm</command> uses dak's configuration file. It follows the typical ISC configuration format as seen in ISC tools like bind 8 and dhcpd.  Apart from being able to alter the defaults for command line options, the following configuration items are used:</para>
 145       <variablelist>
 146         <varlistentry>
 147           <term>Rm::MyEmailAddress</term>
 148           <listitem>
 149             <para>This is used as the From: line for bug closing mails as per the -d/--done command line switch.  It, obviously, must be a RFC-822 valid email address.</para>
 150           </listitem>
 151         </varlistentry>
 152         <varlistentry>
 153           <term>Rm::LogFile</term>
 154           <listitem>
 155             <para>This is the (absolute) file name of the logfile that dak rm unconditionally writes too.  This can not be empty or an invalid file.</para>
 156           </listitem>
 157         </varlistentry>
 158       </variablelist>
 159     </refsect1>
 160
 161   <refsect1>
 162     <title>Examples</title>
 163       <para>The first example is of a source+binaries package removal.</para>
 164       <informalexample>
 165         <literallayout>
 166 $ dak rm -d 68136 -m "Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2" gmp1
 167 Working... done.
 168 Will remove the following packages from unstable:
 169
 170       gmp1 |  1.3.2-8.2 | source, alpha, hppa, arm, i386, m68k, powerpc, sparc
 171   gmp1-dev |  1.3.2-8.2 | alpha, hppa, arm, i386, m68k, powerpc, sparc
 172
 173
 174 ------------------- Reason -------------------
 175 Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2
 176 ----------------------------------------------
 177
 178 Continue (y/N)? y
 179  Deleting... done.
 180 $
 181           </literallayout>
 182       </informalexample>
 183       <para>The second example is of a binary-only multi-package removal.</para>
 184       <informalexample>
 185         <literallayout>
 186 $ dak rm -d 82562 -m "Requested by paul@; NBS." -b libgtkextra{5,9,10}
 187 Working... done.
 188 Will remove the following packages from unstable:
 189
 190 libgtkextra10 |  0.99.10-2 | alpha, i386, m68k, powerpc, sparc
 191 libgtkextra5 |   0.99.5-1 | alpha, i386, m68k, powerpc, sparc
 192 libgtkextra9 |   0.99.9-1 | alpha, i386, m68k, powerpc, sparc
 193
 194 Will also close bugs: 82562
 195
 196 ------------------- Reason -------------------
 197 Requested by paul@; NBS.
 198 ----------------------------------------------
 199
 200 Continue (y/N)? y
 201  Deleting... done.
 202 $
 203         </literallayout>
 204       </informalexample>
 205   </refsect1>
 206
 207   <RefSect1><Title>Diagnostics</>
 208     <para>
 209       <command>dak rm</command> returns zero on normal operation, non-zero on error.
 210     </PARA>
 211   </RefSect1>
 212
 213   &manauthor;
 214
 215 </refentry>