mdw@git.distorted.org.uk Git - dpkg/blob - 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 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 \-\-all
 126 Include all changes. Note: other options have no effect when this is in use.
 127 .TP
 128 .BR \-s ", " \-\-since " \fIversion\fP"
 129 .TQ
 130 .BR \-v " \fIversion\fP"
 131 Include all changes later than \fIversion\fP.
 132 .TP
 133 .BR \-u ", " \-\-until " \fIversion\fP"
 134 Include all changes earlier than \fIversion\fP.
 135 .TP
 136 .BR \-f ", " \-\-from " \fIversion\fP"
 137 Include all changes equal or later than \fIversion\fP.
 138 .TP
 139 .BR \-t ", " \-\-to " \fIversion\fP"
 140 Include all changes up to or equal than \fIversion\fP.
 141 .TP
 142 .BR \-c ", " \-\-count " \fInumber\fP"
 143 .TQ
 144 .BR \-n " \fInumber\fP"
 145 Include \fInumber\fP entries from the top (or the tail
 146 if \fInumber\fP is lower than 0).
 147 .TP
 148 .BR \-o ", " \-\-offset " \fInumber\fP"
 149 Change the starting point for \fB\-\-count\fP, counted from the top
 150 (or the tail if \fInumber\fP is lower than 0).
 151 .
 152 .SH CHANGELOG FORMATS
 153 It is possible to use a different format to the standard one, by providing
 154 a parser for that alternative format.
 155
 156 In order to have \fBdpkg\-parsechangelog\fP run the new parser, a line must
 157 be included within the last 40 lines of the changelog file, matching the Perl
 158 regular expression: “\fB\\schangelog-format:\\s+([0-9a-z]+)\\W\fP”.
 159 The part in parentheses should be the name of the format. For example:
 160
 161        @@@ changelog-format: \fIotherformat\fP @@@
 162
 163 Changelog format names are non-empty strings of alphanumerics.
 164
 165 If such a line exists then \fBdpkg\-parsechangelog\fP will look for
 166 the parser as a \fBDpkg::Changelog::\fP\fIOtherformat\fP perl module;
 167 it is an error for it not being present.
 168 The parser name in the perl module will be automatically capitalized.
 169 The default changelog format is \fBdebian\fP, and a parser for it is
 170 provided by default.
 171
 172 The parser should be derived from the Dpkg::Changelog class and implement
 173 the required documented interface.
 174
 175 If the changelog format which is being parsed always or almost always
 176 leaves a blank line between individual change notes, these blank lines
 177 should be stripped out, so as to make the resulting output compact.
 178
 179 If the changelog format does not contain date or package name information
 180 this information should be omitted from the output. The parser should not
 181 attempt to synthesize it or find it from other sources.
 182
 183 If the changelog does not have the expected format the parser should
 184 error out, rather than trying to muddle through and possibly generating
 185 incorrect output.
 186
 187 A changelog parser may not interact with the user at all.
 188 .
 189 .SH NOTES
 190 All \fBParser Options\fP except for \fB\-v\fP are only supported
 191 since dpkg 1.14.16.
 192 .PP
 193 Short option parsing with non-bundled values available only since dpkg 1.18.0.
 194 .
 195 .SH FILES
 196 .TP
 197 .B debian/changelog
 198 The changelog file, used to obtain version-dependent information about
 199 the source package, such as the urgency and distribution of an upload,
 200 the changes made since a particular release, and the source version
 201 number itself.
 202 .
 203 .SH SEE ALSO
 204 .BR deb\-changelog (5).