]> git.decadent.org.uk Git - dak.git/blob - docs/melanie.1.sgml
sync
[dak.git] / 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
37   <RefSect1><Title>Options</>
38     
39     <VariableList>
40       <VarListEntry><term><option>-a/--architecture=<replaceable>architecture</replaceable></option></>
41         <ListItem><Para>
42             Restrict the packages being considered to the architecture(s) listed.
43       </VarListEntry>
44
45       <VarListEntry><term><option>-b/--binary</option></>
46         <ListItem><Para>
47             Only look at binary packages.
48       </VarListEntry>
49
50       <VarListEntry><term><option>-c/--component=<replaceable>component</replaceable></option></>
51         <ListItem><Para>
52             Restrict the packages being considered to those found in the component(s) listed.  The default is <literal>main</literal>.
53       </VarListEntry>
54
55       <VarListEntry><term><option>-d/--done=<replaceable>done</replaceable></option></>
56         <ListItem><Para>
57             Close the bug(s) listed on successful completion.
58       </VarListEntry>
59
60       <VarListEntry><term><option>-m/--reason=<replaceable>reason</replaceable></option></>
61         <ListItem><Para>
62             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.
63       </VarListEntry>
64
65       <VarListEntry><term><option>-n/--no-action</option></>
66         <ListItem><Para>
67             Don't actually do anything; just show what would be done.
68       </VarListEntry>
69
70       <VarListEntry><term><option>-p/--partial</option></>
71         <ListItem><Para>
72             Partial removal of a package, so the package is not removed from the overrides.  This option is implied by <option>-a/--architecture</option>.
73       </VarListEntry>
74
75       <VarListEntry><term><option>-s/--suite=<replaceable>suite</replaceable></option></>
76         <ListItem><Para>
77             Only add/remove the packages from the suite(s) listed.  The default is <literal>unstable</literal>
78       </VarListEntry>
79
80       <VarListEntry><term><option>-S/--source-only</option></>
81         <ListItem><Para>
82             Only look at source packages.
83       </VarListEntry>
84
85     </VariableList>
86   </RefSect1>
87
88     <refsect1>
89       <title>How packages are chosen</title>
90       <para>There are 3 methods for selecting packages.</para>
91       <itemizedlist>
92         <listitem>
93           <para>Source + Binaries. (default)</para>
94           <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>
95         </listitem>
96         <listitem>
97           <para>Binary only.</para>
98           <para>Only binary packages are searched; source packages are ignored.  This mode is chosen by use of the <option>-b/--binary</option> switch.</para>
99           <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>
100         </listitem>
101         <listitem>
102           <para>Source only.</para>
103           <para>Only source packages are searched; binary packages are ignored.  This mode is chosen by use of the <option>-S/--source</option> switch.</para>
104         </listitem>
105       </itemizedlist>
106     </refsect1>
107
108     <refsect1>
109       <title>Configuration</title>
110       <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>
111       <variablelist>
112         <varlistentry>
113           <term>Melanie::MyEmailAddress</term>
114           <listitem>
115             <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>
116           </listitem>
117         </varlistentry>
118         <varlistentry>
119           <term>Melanie::LogFile</term>
120           <listitem>
121             <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>
122           </listitem>
123         </varlistentry>
124       </variablelist>
125     </refsect1>
126
127   <refsect1>
128     <title>Examples</title>
129       <para>The first example is of a source+binaries package removal.</para>
130       <informalexample>
131         <literallayout>
132 troup@auric| ~ $melanie -d 68136 -m "Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2" gmp1   
133 Working... done.
134 Will remove the following packages from unstable:
135
136       gmp1 |  1.3.2-8.2 | source, alpha, hppa, arm, i386, m68k, powerpc, sparc
137   gmp1-dev |  1.3.2-8.2 | alpha, hppa, arm, i386, m68k, powerpc, sparc
138
139
140 ------------------- Reason -------------------
141 Requested by tbm@; confirmed with maintainer.  Superseded by libgmp2
142 ----------------------------------------------
143
144 Continue (y/N)? y
145  Deleting... done.
146 troup@auric| ~ $
147           </literallayout>
148       </informalexample>
149       <para>The second example is of a binary-only multi-package removal.</para>
150       <informalexample>
151         <literallayout>
152 troup@auric| ~ $melanie -d 82562 -m "Requested by paul@; NBS." -b libgtkextra{5,9,10}
153 Working... done.
154 Will remove the following packages from unstable:
155
156 libgtkextra10 |  0.99.10-2 | alpha, i386, m68k, powerpc, sparc
157 libgtkextra5 |   0.99.5-1 | alpha, i386, m68k, powerpc, sparc
158 libgtkextra9 |   0.99.9-1 | alpha, i386, m68k, powerpc, sparc
159
160 Will also close bugs: 82562
161
162 ------------------- Reason -------------------
163 Requested by paul@; NBS.
164 ----------------------------------------------
165
166 Continue (y/N)? y
167  Deleting... done.
168 troup@auric| ~ $
169         </literallayout>
170       </informalexample>
171   </refsect1>
172
173   <RefSect1><Title>Diagnostics</>
174     <para>
175       <command>melanie</command> returns zero on normal operation, non-zero on error.
176   </RefSect1>
177
178   &manauthor;
179   
180 </refentry>