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. By default the format is read
  54 from a special line near the bottom of the changelog or failing that
  55 defaults to the B<debian> standard format. See also
  56 B<CHANGELOG FORMATS>.
  57
  58 =item B<-L> I<libdir>
  59
  60 Obsolete option without effect (since dpkg 1.18.8).
  61 Setting the perl environment variables B<PERL5LIB> or B<PERLLIB>
  62 has a similar effect when looking for the parser perl modules.
  63
  64 =item B<-S>, B<--show-field> I<field>
  65
  66 Specifies the name of the field to show (since dpkg 1.17.0).
  67 The field name is not printed, only its value.
  68
  69 =item B<-?>, B<--help>
  70
  71 Show the usage message and exit.
  72
  73 =item B<--version>
  74
  75 Show the version and exit.
  76
  77 =back
  78
  79 =head2 Parser Options
  80
  81 The following options can be used to influence the output of
  82 the changelog parser, e.g. the range of entries or the format
  83 of the output.
  84
  85 =over
  86
  87 =item B<--format> I<output-format>
  88
  89 Set the output format. Currently supported values are
  90 B<dpkg> and B<rfc822>.
  91 B<dpkg> is the classic output format (from before this
  92 option existed) and the default. It consists of one paragraph
  93 in Debian control format (see B<deb-control>(5)). If more
  94 than one entry is requested, then most fields are taken from the
  95 first entry (usually the most recent entry), except otherwise stated:
  96
  97 =over
  98
  99 =item B<Source:> I<pkg-name>
 100
 101 =item B<Version:> I<version>
 102
 103 =item B<Distribution:> I<target-distribution>
 104
 105 =item B<Urgency:> I<urgency>
 106
 107 The highest urgency of all included entries is used, followed by the
 108 concatenated (space-separated) comments from all the versions requested.
 109
 110 =item B<Maintainer:> I<author>
 111
 112 =item B<Date:> I<date>
 113
 114 The date of the entry as a string, as it appears in the changelog.
 115 With a B<strptime>(3) format "B<%a, %d %b %Y %T %z>", but where the
 116 day of the week might not actually correspond to the real day obtained
 117 from the rest of the date string.
 118 If you need a more accurate representation of the date, use the
 119 B<Timestamp> field, but take into account it might not be possible to
 120 map it back to the exact value in this field.
 121
 122 =item B<Timestamp:> I<timestamp>
 123
 124 The date of the entry as a timestamp in seconds since the epoch
 125 (since dpkg 1.18.8).
 126
 127 =item B<Closes:> I<bug-number>
 128
 129 The Closes fields of all included entries are merged.
 130
 131 =item B<Changes:> I<changelog-entries>
 132
 133 The text of all changelog entries is concatenated. To make
 134 this field a valid Debian control format multiline field
 135 empty lines are replaced with a single full stop and all lines
 136 is intended by one space character. The exact content depends
 137 on the changelog format.
 138
 139 =back
 140
 141 The B<Version>, B<Distribution>, B<Urgency>, B<Maintainer> and
 142 B<Changes> fields are mandatory.
 143
 144 There might be additional user-defined fields present.
 145
 146 The B<rfc822> format uses the same fields but outputs
 147 a separate paragraph for each changelog entry so that all
 148 metadata for each entry is preserved.
 149
 150 =item B<--reverse>
 151
 152 Include all changes in reverse order (since dpkg 1.19.1).
 153
 154 B<Note:> For the B<dpkg> format the first entry will be the most ancient
 155 entry.
 156
 157 =item B<--all>
 158
 159 Include all changes.
 160 B<Note:> Other options have no effect when this is in use.
 161
 162 =item B<-s>, B<--since> I<version>
 163
 164 =item B<-v> I<version>
 165
 166 Include all changes later than I<version>.
 167
 168 =item B<-u>, B<--until> I<version>
 169
 170 Include all changes earlier than I<version>.
 171
 172 =item B<-f>, B<--from> I<version>
 173
 174 Include all changes equal or later than I<version>.
 175
 176 =item B<-t>, B<--to> I<version>
 177
 178 Include all changes up to or equal than I<version>.
 179
 180 =item B<-c>, B<--count> I<number>
 181
 182 =item B<-n> I<number>
 183
 184 Include I<number> entries from the top (or the tail
 185 if I<number> is lower than 0).
 186
 187 =item B<-o>, B<--offset> I<number>
 188
 189 Change the starting point for B<--count>, counted from the top
 190 (or the tail if I<number> is lower than 0).
 191
 192 =back
 193
 194 =head1 CHANGELOG FORMATS
 195
 196 It is possible to use a different format to the standard one, by providing
 197 a parser for that alternative format.
 198
 199 In order to have B<dpkg-parsechangelog> run the new parser, a line must
 200 be included within the last 40 lines of the changelog file, matching the Perl
 201 regular expression: “B<\schangelog-format:\s+([0-9a-z]+)\W>”.
 202 The part in parentheses should be the name of the format. For example:
 203
 204 =over
 205
 206 @@@ changelog-format: I<otherformat> @@@
 207
 208 =back
 209
 210 Changelog format names are non-empty strings of lowercase alphanumerics
 211 (“a-z0-9”).
 212
 213 If such a line exists then B<dpkg-parsechangelog> will look for
 214 the parser as a B<Dpkg::Changelog::>I<Otherformat> perl module;
 215 it is an error for it not being present.
 216 The parser name in the perl module will be automatically capitalized.
 217 The default changelog format is B<debian>, and a parser for it is
 218 provided by default.
 219
 220 The parser should be derived from the Dpkg::Changelog class and implement
 221 the required documented interface.
 222
 223 If the changelog format which is being parsed always or almost always
 224 leaves a blank line between individual change notes, these blank lines
 225 should be stripped out, so as to make the resulting output compact.
 226
 227 If the changelog format does not contain date or package name information
 228 this information should be omitted from the output. The parser should not
 229 attempt to synthesize it or find it from other sources.
 230
 231 If the changelog does not have the expected format the parser should
 232 error out, rather than trying to muddle through and possibly generating
 233 incorrect output.
 234
 235 A changelog parser may not interact with the user at all.
 236
 237 =head1 NOTES
 238
 239 All B<Parser Options> except for B<-v> are only supported
 240 since dpkg 1.14.16.
 241
 242 Short option parsing with non-bundled values available only since dpkg 1.18.0.
 243
 244 =head1 ENVIRONMENT
 245
 246 =over
 247
 248 =item B<DPKG_COLORS>
 249
 250 Sets the color mode (since dpkg 1.18.5).
 251 The currently accepted values are: B<auto> (default), B<always> and
 252 B<never>.
 253
 254 =item B<DPKG_NLS>
 255
 256 If set, it will be used to decide whether to activate Native Language Support,
 257 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 258 The accepted values are: B<0> and B<1> (default).
 259
 260 =back
 261
 262 =head1 FILES
 263
 264 =over
 265
 266 =item B<debian/changelog>
 267
 268 The changelog file, used to obtain version-dependent information about
 269 the source package, such as the urgency and distribution of an upload,
 270 the changes made since a particular release, and the source version
 271 number itself.
 272
 273 =back
 274
 275 =head1 SEE ALSO
 276
 277 B<deb-changelog>(5).