Commit | Line | Data |
---|---|---|
1479465f GJ |
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). |