docs/melanie.1.sgml

   1 <!-- -*- mode: sgml; mode: fold -*- -->
   2 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   3
   4 <!ENTITY % katieent SYSTEM "katie.ent">
   5 %katieent;
   6
   7 ]>
   8
   9 <refentry>
  10   &katie-docinfo;
  11
  12   <refmeta>
  13     <refentrytitle>melanie</>
  14     <manvolnum>1</>
  15   </refmeta>
  16
  17   <!-- Man page title -->
  18   <refnamediv>
  19     <refname>melanie</>
  20     <refpurpose>Utility to remove/add packages from suites</>
  21   </refnamediv>
  22
  23   <!-- Arguments -->
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>melanie</>
  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>melanie</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>-s/--suite=<replaceable>suite</replaceable></option></>
 102         <ListItem>
 103           <Para>Only add/remove the packages from the suite(s) listed.  The default is <literal>unstable</literal></PARA>
 104         </LISTITEM>
 105       </VarListEntry>
 106
 107       <VarListEntry><term><option>-S/--source-only</option></>
 108         <ListItem>
 109           <Para>Only look at source packages.</PARA>
 110         </LISTITEM>
 111       </VarListEntry>
 112
 113     </VariableList>
 114   </RefSect1>
 115
 116     <refsect1>
 117       <title>How packages are chosen</title>
 118       <para>There are 3 methods for selecting packages.</para>
 119       <itemizedlist>
 120         <listitem>
 121           <para>Source + Binaries. (default)</para>
 122           <para>In this mode <command>melanie</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>
 123         </listitem>
 124         <listitem>
 125           <para>Binary only.</para>
 126           <para>Only binary packages are searched; source packages are ignored.  This mode is chosen by use of the <option>-b/--binary</option> switch.</para>
 127           <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>
 128         </listitem>
 129         <listitem>
 130           <para>Source only.</para>
 131           <para>Only source packages are searched; binary packages are ignored.  This mode is chosen by use of the <option>-S/--source</option> switch.</para>
 132         </listitem>
 133       </itemizedlist>
 134     </refsect1>
 135
 136     <refsect1>
 137       <title>Configuration</title>
 138       <para><command>melanie</command> uses katie'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>
 139       <variablelist>
 140         <varlistentry>
 141           <term>Melanie::MyEmailAddress</term>
 142           <listitem>
 143             <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>
 144           </listitem>
 145         </varlistentry>
 146         <varlistentry>
 147           <term>Melanie::LogFile</term>
 148           <listitem>
 149             <para>This is the (absolute) file name of the logfile that melanie unconditionally writes too.  This can not be empty or an invalid file.</para>
 150           </listitem>
 151         </varlistentry>
 152       </variablelist>
 153     </refsect1>
 154
 155   <refsect1>
 156     <title>Examples</title>
 157       <para>The first example is of a source+binaries package removal.</para>
 158       <informalexample>
 159         <literallayout>
 160 troup@auric| ~ $melanie -d 68136 -m "Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2" gmp1
 161 Working... done.
 162 Will remove the following packages from unstable:
 163
 164       gmp1 |  1.3.2-8.2 | source, alpha, hppa, arm, i386, m68k, powerpc, sparc
 165   gmp1-dev |  1.3.2-8.2 | alpha, hppa, arm, i386, m68k, powerpc, sparc
 166
 167
 168 ------------------- Reason -------------------
 169 Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2
 170 ----------------------------------------------
 171
 172 Continue (y/N)? y
 173  Deleting... done.
 174 troup@auric| ~ $
 175           </literallayout>
 176       </informalexample>
 177       <para>The second example is of a binary-only multi-package removal.</para>
 178       <informalexample>
 179         <literallayout>
 180 troup@auric| ~ $melanie -d 82562 -m "Requested by paul@; NBS." -b libgtkextra{5,9,10}
 181 Working... done.
 182 Will remove the following packages from unstable:
 183
 184 libgtkextra10 |  0.99.10-2 | alpha, i386, m68k, powerpc, sparc
 185 libgtkextra5 |   0.99.5-1 | alpha, i386, m68k, powerpc, sparc
 186 libgtkextra9 |   0.99.9-1 | alpha, i386, m68k, powerpc, sparc
 187
 188 Will also close bugs: 82562
 189
 190 ------------------- Reason -------------------
 191 Requested by paul@; NBS.
 192 ----------------------------------------------
 193
 194 Continue (y/N)? y
 195  Deleting... done.
 196 troup@auric| ~ $
 197         </literallayout>
 198       </informalexample>
 199   </refsect1>
 200
 201   <RefSect1><Title>Diagnostics</>
 202     <para>
 203       <command>melanie</command> returns zero on normal operation, non-zero on error.
 204     </PARA>
 205   </RefSect1>
 206
 207   &manauthor;
 208
 209 </refentry>