man/dpkg-parsechangelog.pod

   1 # dpkg manual page - dpkg-parsechangelog(1)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2006, 2011-2015 Guillem Jover <guillem@debian.org>
   6 # Copyright © 2007-2008 Frank Lichtenheld <djpig@debian.org>
   7 # Copyright © 2009 Raphaël Hertzog <hertzog@debian.org>
   8 #
   9 # This is free software; you can redistribute it and/or modify
  10 # it under the terms of the GNU General Public License as published by
  11 # the Free Software Foundation; either version 2 of the License, or
  12 # (at your option) any later version.
  13 #
  14 # This is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 # GNU General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU General Public License
  20 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  21
  22 =encoding utf8
  23
  24 =head1 NAME
  25
  26 dpkg-parsechangelog - parse Debian changelog files
  27
  28 =head1 SYNOPSIS
  29
  30 B<dpkg-parsechangelog>
  31 [I<option>...]
  32
  33 =head1 DESCRIPTION
  34
  35 B<dpkg-parsechangelog>
  36 reads and parses the changelog of an unpacked Debian source tree and
  37 outputs the information in it to standard output in a machine-readable
  38 form.
  39
  40 =head1 OPTIONS
  41
  42 =over
  43
  44 =item B<-l>, B<--file> I<changelog-file>
  45
  46 Specifies the changelog file to read information from.
  47 A ‘-’ can be used to specify reading from standard input.
  48 The default is
  49 B<debian/changelog>.
  50
  51 =item B<-F> I<changelog-format>
  52
  53 Specifies the format of the changelog.
  54 By default the format is read
  55 from a special line near the bottom of the changelog or failing that
  56 defaults to the B<debian> standard format.
  57 See also L</CHANGELOG FORMATS>.
  58
  59 =item B<-L> I<libdir>
  60
  61 Obsolete option without effect (since dpkg 1.18.8).
  62 Setting the perl environment variables B<PERL5LIB> or B<PERLLIB>
  63 has a similar effect when looking for the parser perl modules.
  64
  65 =item B<-S>, B<--show-field> I<field>
  66
  67 Specifies the name of the field to show (since dpkg 1.17.0).
  68 The field name is not printed, only its value.
  69
  70 =item B<-?>, B<--help>
  71
  72 Show the usage message and exit.
  73
  74 =item B<--version>
  75
  76 Show the version and exit.
  77
  78 =back
  79
  80 =head2 Parser Options
  81
  82 The following options can be used to influence the output of
  83 the changelog parser, for example the range of entries or the format
  84 of the output.
  85
  86 =over
  87
  88 =item B<--format> I<output-format>
  89
  90 Set the output format.
  91 Currently supported values are
  92 B<dpkg> and B<rfc822>.
  93 B<dpkg> is the classic output format (from before this
  94 option existed) and the default.
  95 It consists of one stanza in Debian control format (see L<deb-control(5)>).
  96 If more
  97 than one entry is requested, then most fields are taken from the
  98 first entry (usually the most recent entry), except otherwise stated:
  99
 100 =over
 101
 102 =item B<Source:> I<pkg-name>
 103
 104 The source package name.
 105
 106 =item B<Version:> I<version>
 107
 108 The source version number.
 109 B<Note>: For binary-only releases there might be no corresponding source
 110 release.
 111
 112 =item B<Distribution:> I<target-distribution>
 113
 114 A space-separated list of one or more distribution names where this version
 115 should be installed when it is uploaded.
 116
 117 =item B<Urgency:> I<urgency>
 118
 119 The highest urgency of all included entries is used, followed by the
 120 concatenated (space-separated) comments from all the versions requested.
 121
 122 =item B<Maintainer:> I<author>
 123
 124 The name and email address of the person who prepared these changes,
 125 they are B<not> necessarily those of the uploader or the usual package
 126 maintainer.
 127
 128 =item B<Date:> I<date>
 129
 130 The date of the entry as a string, as it appears in the changelog.
 131 With a L<strptime(3)> format "B<%a, %d %b %Y %T %z>", but where the
 132 day of the week might not actually correspond to the real day obtained
 133 from the rest of the date string.
 134 If you need a more accurate representation of the date, use the
 135 B<Timestamp> field, but take into account it might not be possible to
 136 map it back to the exact value in this field.
 137
 138 =item B<Timestamp:> I<timestamp>
 139
 140 The date of the entry as a timestamp in seconds since the epoch
 141 (since dpkg 1.18.8).
 142
 143 =item B<Closes:> I<bug-number>
 144
 145 The Closes fields of all included entries are merged.
 146
 147 =item B<Changes:> I<changelog-entries>
 148
 149 The text of all changelog entries is concatenated.
 150 To make
 151 this field a valid Debian control format multiline field
 152 empty lines are replaced with a single full stop and all lines
 153 is intended by one space character.
 154 The exact content depends
 155 on the changelog format.
 156
 157 =back
 158
 159 The B<Version>, B<Distribution>, B<Urgency>, B<Maintainer> and
 160 B<Changes> fields are mandatory.
 161
 162 There might be additional user-defined fields present.
 163
 164 The B<rfc822> format uses the same fields but outputs
 165 a separate stanza for each changelog entry so that all
 166 metadata for each entry is preserved.
 167
 168 =item B<--reverse>
 169
 170 Include all changes in reverse order (since dpkg 1.19.1).
 171
 172 B<Note>: For the B<dpkg> format the first entry will be the most ancient
 173 entry.
 174
 175 =item B<--all>
 176
 177 Include all changes.
 178 B<Note>: Other options have no effect when this is in use.
 179
 180 =item B<-s>, B<--since> I<version>
 181
 182 =item B<-v> I<version>
 183
 184 Include all changes later than I<version>.
 185
 186 =item B<-u>, B<--until> I<version>
 187
 188 Include all changes earlier than I<version>.
 189
 190 =item B<-f>, B<--from> I<version>
 191
 192 Include all changes equal or later than I<version>.
 193
 194 =item B<-t>, B<--to> I<version>
 195
 196 Include all changes up to or equal than I<version>.
 197
 198 =item B<-c>, B<--count> I<number>
 199
 200 =item B<-n> I<number>
 201
 202 Include I<number> entries from the top (or the tail
 203 if I<number> is lower than 0).
 204
 205 =item B<-o>, B<--offset> I<number>
 206
 207 Change the starting point for B<--count>, counted from the top
 208 (or the tail if I<number> is lower than 0).
 209
 210 =back
 211
 212 =head1 CHANGELOG FORMATS
 213
 214 It is possible to use a different format to the standard one, by providing
 215 a parser for that alternative format.
 216
 217 In order to have B<dpkg-parsechangelog> run the new parser, a line must
 218 be included within the last 40 lines of the changelog file, matching the Perl
 219 regular expression: “B<\schangelog-format:\s+([0-9a-z]+)\W>”.
 220 The part in parentheses should be the name of the format.
 221 For example:
 222
 223 =over
 224
 225 @@@ changelog-format: I<otherformat> @@@
 226
 227 =back
 228
 229 Changelog format names are non-empty strings of lowercase alphanumerics
 230 (“a-z0-9”).
 231
 232 If such a line exists then B<dpkg-parsechangelog> will look for
 233 the parser as a B<Dpkg::Changelog::>I<Otherformat> perl module;
 234 it is an error for it not being present.
 235 The parser name in the perl module will be automatically capitalized.
 236 The default changelog format is B<debian>, and a parser for it is
 237 provided by default.
 238
 239 The parser should be derived from the L<Dpkg::Changelog> class and implement
 240 the required documented interface.
 241
 242 If the changelog format which is being parsed always or almost always
 243 leaves a blank line between individual change notes, these blank lines
 244 should be stripped out, so as to make the resulting output compact.
 245
 246 If the changelog format does not contain date or package name information
 247 this information should be omitted from the output.
 248 The parser should not
 249 attempt to synthesize it or find it from other sources.
 250
 251 If the changelog does not have the expected format the parser should
 252 error out, rather than trying to muddle through and possibly generating
 253 incorrect output.
 254
 255 A changelog parser may not interact with the user at all.
 256
 257 =head1 NOTES
 258
 259 All B<Parser Options> except for B<-v> are only supported
 260 since dpkg 1.14.16.
 261
 262 Short option parsing with non-bundled values available only since dpkg 1.18.0.
 263
 264 =head1 ENVIRONMENT
 265
 266 =over
 267
 268 =item B<DPKG_COLORS>
 269
 270 Sets the color mode (since dpkg 1.18.5).
 271 The currently accepted values are: B<auto> (default), B<always> and
 272 B<never>.
 273
 274 =item B<DPKG_NLS>
 275
 276 If set, it will be used to decide whether to activate Native Language Support,
 277 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 278 The accepted values are: B<0> and B<1> (default).
 279
 280 =back
 281
 282 =head1 FILES
 283
 284 =over
 285
 286 =item B<debian/changelog>
 287
 288 The changelog file, used to obtain version-dependent information about
 289 the source package, such as the urgency and distribution of an upload,
 290 the changes made since a particular release, and the source version
 291 number itself.
 292
 293 =back
 294
 295 =head1 BUGS
 296
 297 The B<Maintainer> field has a confusing name matching the field in
 298 the F<debian/control> file but not its exact semantics,
 299 where its meaning would be better represented by the B<Changed-By> field
 300 name used in the F<.changes> file.
 301
 302 =head1 SEE ALSO
 303
 304 L<deb-changelog(5)>.