man/dpkg-parsechangelog.man

   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 .TH dpkg\-parsechangelog 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  23 .nh
  24 .SH NAME
  25 dpkg\-parsechangelog \- parse Debian changelog files
  26 .
  27 .SH SYNOPSIS
  28 .B dpkg\-parsechangelog
  29 .RI [ option ...]
  30 .
  31 .SH DESCRIPTION
  32 .B dpkg\-parsechangelog
  33 reads and parses the changelog of an unpacked Debian source tree and
  34 outputs the information in it to standard output in a machine-readable
  35 form.
  36 .
  37 .SH OPTIONS
  38 .TP
  39 .BR \-l ", " \-\-file " \fIchangelog-file\fP"
  40 Specifies the changelog file to read information from.
  41 A ‘\-’ can be used to specify reading from standard input.
  42 The default is
  43 .BR debian/changelog .
  44 .TP
  45 .BR \-F " \fIchangelog-format\fP"
  46 Specifies the format of the changelog. By default the format is read
  47 from a special line near the bottom of the changelog or failing that
  48 defaults to the \fBdebian\fP standard format. See also
  49 \fBCHANGELOG FORMATS\fP.
  50 .TP
  51 .BR \-L " \fIlibdir\fP"
  52 Obsolete option without effect (since dpkg 1.18.8).
  53 Setting the perl environment variables \fBPERL5LIB\fP or \fBPERLLIB\fP
  54 has a similar effect when looking for the parser perl modules.
  55 .TP
  56 .BR \-S ", " \-\-show\-field " \fIfield\fP"
  57 Specifies the name of the field to show (since dpkg 1.17.0).
  58 The field name is not printed, only its value.
  59 .TP
  60 .BR \-? ", " \-\-help
  61 Show the usage message and exit.
  62 .TP
  63 .BR \-\-version
  64 Show the version and exit.
  65 .SS Parser Options
  66 The following options can be used to influence the output of
  67 the changelog parser, e.g. the range of entries or the format
  68 of the output.
  69 .TP
  70 .BI \-\-format " output-format"
  71 Set the output format. Currently supported values are
  72 .BR dpkg " and " rfc822 .
  73 \fBdpkg\fP is the classic output format (from before this
  74 option existed) and the default. It consists of one paragraph
  75 in Debian control format (see \fBdeb\-control\fP(5)). If more
  76 than one entry is requested, then most fields are taken from the
  77 first entry (usually the most recent entry), except otherwise stated:
  78 .RS
  79 .TP
  80 .BI Source: " pkg-name"
  81 .TP
  82 .BI Version: " version"
  83 .TP
  84 .BI Distribution: " target-distribution"
  85 .TP
  86 .BI Urgency: " urgency"
  87 The highest urgency of all included entries is used, followed by the
  88 concatenated (space-separated) comments from all the versions requested.
  89 .TP
  90 .BI Maintainer: " author"
  91 .TP
  92 .BI Date: " date"
  93 The date of the entry as a string, as it appears in the changelog.
  94 With a \fBstrptime\fP(3) format "\fB%a, %d %b %Y %T %z\fP", but where the
  95 day of the week might not actually correspond to the real day obtained
  96 from the rest of the date string.
  97 If you need a more accurate representation of the date, use the
  98 \fBTimestamp\fP field, but take into account it might not be possible to
  99 map it back to the exact value in this field.
 100 .TP
 101 .BI Timestamp: " timestamp"
 102 The date of the entry as a timestamp in seconds since the epoch
 103 (since dpkg 1.18.8).
 104 .TP
 105 .BI Closes: " bug-number"
 106 The Closes fields of all included entries are merged.
 107 .TP
 108 .BI Changes: " changelog-entries"
 109 The text of all changelog entries is concatenated. To make
 110 this field a valid Debian control format multiline field
 111 empty lines are replaced with a single full stop and all lines
 112 is intended by one space character. The exact content depends
 113 on the changelog format.
 114 .RE
 115 .IP
 116 The \fBVersion\fP, \fBDistribution\fP, \fBUrgency\fP, \fBMaintainer\fP and
 117 \fBChanges\fP fields are mandatory.
 118 .IP
 119 There might be additional user-defined fields present.
 120 .IP
 121 The \fBrfc822\fP format uses the same fields but outputs
 122 a separate paragraph for each changelog entry so that all
 123 metadata for each entry is preserved.
 124 .TP
 125 .B \-\-reverse
 126 Include all changes in reverse order (since dpkg 1.19.1).
 127 Note: for the \fBdpkg\fP format the first entry will be the most ancient entry.
 128 .TP
 129 .B \-\-all
 130 Include all changes. Note: other options have no effect when this is in use.
 131 .TP
 132 .BR \-s ", " \-\-since " \fIversion\fP"
 133 .TQ
 134 .BR \-v " \fIversion\fP"
 135 Include all changes later than \fIversion\fP.
 136 .TP
 137 .BR \-u ", " \-\-until " \fIversion\fP"
 138 Include all changes earlier than \fIversion\fP.
 139 .TP
 140 .BR \-f ", " \-\-from " \fIversion\fP"
 141 Include all changes equal or later than \fIversion\fP.
 142 .TP
 143 .BR \-t ", " \-\-to " \fIversion\fP"
 144 Include all changes up to or equal than \fIversion\fP.
 145 .TP
 146 .BR \-c ", " \-\-count " \fInumber\fP"
 147 .TQ
 148 .BR \-n " \fInumber\fP"
 149 Include \fInumber\fP entries from the top (or the tail
 150 if \fInumber\fP is lower than 0).
 151 .TP
 152 .BR \-o ", " \-\-offset " \fInumber\fP"
 153 Change the starting point for \fB\-\-count\fP, counted from the top
 154 (or the tail if \fInumber\fP is lower than 0).
 155 .
 156 .SH CHANGELOG FORMATS
 157 It is possible to use a different format to the standard one, by providing
 158 a parser for that alternative format.
 159
 160 In order to have \fBdpkg\-parsechangelog\fP run the new parser, a line must
 161 be included within the last 40 lines of the changelog file, matching the Perl
 162 regular expression: “\fB\\schangelog-format:\\s+([0-9a-z]+)\\W\fP”.
 163 The part in parentheses should be the name of the format. For example:
 164
 165        @@@ changelog-format: \fIotherformat\fP @@@
 166
 167 Changelog format names are non-empty strings of lowercase alphanumerics
 168 (“a-z0-9”).
 169
 170 If such a line exists then \fBdpkg\-parsechangelog\fP will look for
 171 the parser as a \fBDpkg::Changelog::\fP\fIOtherformat\fP perl module;
 172 it is an error for it not being present.
 173 The parser name in the perl module will be automatically capitalized.
 174 The default changelog format is \fBdebian\fP, and a parser for it is
 175 provided by default.
 176
 177 The parser should be derived from the Dpkg::Changelog class and implement
 178 the required documented interface.
 179
 180 If the changelog format which is being parsed always or almost always
 181 leaves a blank line between individual change notes, these blank lines
 182 should be stripped out, so as to make the resulting output compact.
 183
 184 If the changelog format does not contain date or package name information
 185 this information should be omitted from the output. The parser should not
 186 attempt to synthesize it or find it from other sources.
 187
 188 If the changelog does not have the expected format the parser should
 189 error out, rather than trying to muddle through and possibly generating
 190 incorrect output.
 191
 192 A changelog parser may not interact with the user at all.
 193 .
 194 .SH NOTES
 195 All \fBParser Options\fP except for \fB\-v\fP are only supported
 196 since dpkg 1.14.16.
 197 .PP
 198 Short option parsing with non-bundled values available only since dpkg 1.18.0.
 199 .
 200 .SH ENVIRONMENT
 201 .TP
 202 .B DPKG_COLORS
 203 Sets the color mode (since dpkg 1.18.5).
 204 The currently accepted values are: \fBauto\fP (default), \fBalways\fP and
 205 \fBnever\fP.
 206 .TP
 207 .B DPKG_NLS
 208 If set, it will be used to decide whether to activate Native Language Support,
 209 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 210 The accepted values are: \fB0\fP and \fB1\fP (default).
 211 .
 212 .SH FILES
 213 .TP
 214 .B debian/changelog
 215 The changelog file, used to obtain version-dependent information about
 216 the source package, such as the urgency and distribution of an upload,
 217 the changes made since a particular release, and the source version
 218 number itself.
 219 .
 220 .SH SEE ALSO
 221 .BR deb\-changelog (5).