diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/dpkg-parsechangelog.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/dpkg-parsechangelog.pod | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/man/dpkg-parsechangelog.pod b/man/dpkg-parsechangelog.pod new file mode 100644 index 0000000..c1722d0 --- /dev/null +++ b/man/dpkg-parsechangelog.pod @@ -0,0 +1,277 @@ +# dpkg manual page - dpkg-parsechangelog(1) +# +# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk> +# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2006, 2011-2015 Guillem Jover <guillem@debian.org> +# Copyright © 2007-2008 Frank Lichtenheld <djpig@debian.org> +# Copyright © 2009 Raphaël Hertzog <hertzog@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +dpkg-parsechangelog - parse Debian changelog files + +=head1 SYNOPSIS + +B<dpkg-parsechangelog> +[I<option>...] + +=head1 DESCRIPTION + +B<dpkg-parsechangelog> +reads and parses the changelog of an unpacked Debian source tree and +outputs the information in it to standard output in a machine-readable +form. + +=head1 OPTIONS + +=over + +=item B<-l>, B<--file> I<changelog-file> + +Specifies the changelog file to read information from. +A ‘-’ can be used to specify reading from standard input. +The default is +B<debian/changelog>. + +=item B<-F> I<changelog-format> + +Specifies the format of the changelog. By default the format is read +from a special line near the bottom of the changelog or failing that +defaults to the B<debian> standard format. See also +B<CHANGELOG FORMATS>. + +=item B<-L> I<libdir> + +Obsolete option without effect (since dpkg 1.18.8). +Setting the perl environment variables B<PERL5LIB> or B<PERLLIB> +has a similar effect when looking for the parser perl modules. + +=item B<-S>, B<--show-field> I<field> + +Specifies the name of the field to show (since dpkg 1.17.0). +The field name is not printed, only its value. + +=item B<-?>, B<--help> + +Show the usage message and exit. + +=item B<--version> + +Show the version and exit. + +=back + +=head2 Parser Options + +The following options can be used to influence the output of +the changelog parser, e.g. the range of entries or the format +of the output. + +=over + +=item B<--format> I<output-format> + +Set the output format. Currently supported values are +B<dpkg> and B<rfc822>. +B<dpkg> is the classic output format (from before this +option existed) and the default. It consists of one paragraph +in Debian control format (see B<deb-control>(5)). If more +than one entry is requested, then most fields are taken from the +first entry (usually the most recent entry), except otherwise stated: + +=over + +=item B<Source:> I<pkg-name> + +=item B<Version:> I<version> + +=item B<Distribution:> I<target-distribution> + +=item B<Urgency:> I<urgency> + +The highest urgency of all included entries is used, followed by the +concatenated (space-separated) comments from all the versions requested. + +=item B<Maintainer:> I<author> + +=item B<Date:> I<date> + +The date of the entry as a string, as it appears in the changelog. +With a B<strptime>(3) format "B<%a, %d %b %Y %T %z>", but where the +day of the week might not actually correspond to the real day obtained +from the rest of the date string. +If you need a more accurate representation of the date, use the +B<Timestamp> field, but take into account it might not be possible to +map it back to the exact value in this field. + +=item B<Timestamp:> I<timestamp> + +The date of the entry as a timestamp in seconds since the epoch +(since dpkg 1.18.8). + +=item B<Closes:> I<bug-number> + +The Closes fields of all included entries are merged. + +=item B<Changes:> I<changelog-entries> + +The text of all changelog entries is concatenated. To make +this field a valid Debian control format multiline field +empty lines are replaced with a single full stop and all lines +is intended by one space character. The exact content depends +on the changelog format. + +=back + +The B<Version>, B<Distribution>, B<Urgency>, B<Maintainer> and +B<Changes> fields are mandatory. + +There might be additional user-defined fields present. + +The B<rfc822> format uses the same fields but outputs +a separate paragraph for each changelog entry so that all +metadata for each entry is preserved. + +=item B<--reverse> + +Include all changes in reverse order (since dpkg 1.19.1). + +B<Note:> For the B<dpkg> format the first entry will be the most ancient +entry. + +=item B<--all> + +Include all changes. +B<Note:> Other options have no effect when this is in use. + +=item B<-s>, B<--since> I<version> + +=item B<-v> I<version> + +Include all changes later than I<version>. + +=item B<-u>, B<--until> I<version> + +Include all changes earlier than I<version>. + +=item B<-f>, B<--from> I<version> + +Include all changes equal or later than I<version>. + +=item B<-t>, B<--to> I<version> + +Include all changes up to or equal than I<version>. + +=item B<-c>, B<--count> I<number> + +=item B<-n> I<number> + +Include I<number> entries from the top (or the tail +if I<number> is lower than 0). + +=item B<-o>, B<--offset> I<number> + +Change the starting point for B<--count>, counted from the top +(or the tail if I<number> is lower than 0). + +=back + +=head1 CHANGELOG FORMATS + +It is possible to use a different format to the standard one, by providing +a parser for that alternative format. + +In order to have B<dpkg-parsechangelog> run the new parser, a line must +be included within the last 40 lines of the changelog file, matching the Perl +regular expression: “B<\schangelog-format:\s+([0-9a-z]+)\W>”. +The part in parentheses should be the name of the format. For example: + +=over + +@@@ changelog-format: I<otherformat> @@@ + +=back + +Changelog format names are non-empty strings of lowercase alphanumerics +(“a-z0-9”). + +If such a line exists then B<dpkg-parsechangelog> will look for +the parser as a B<Dpkg::Changelog::>I<Otherformat> perl module; +it is an error for it not being present. +The parser name in the perl module will be automatically capitalized. +The default changelog format is B<debian>, and a parser for it is +provided by default. + +The parser should be derived from the Dpkg::Changelog class and implement +the required documented interface. + +If the changelog format which is being parsed always or almost always +leaves a blank line between individual change notes, these blank lines +should be stripped out, so as to make the resulting output compact. + +If the changelog format does not contain date or package name information +this information should be omitted from the output. The parser should not +attempt to synthesize it or find it from other sources. + +If the changelog does not have the expected format the parser should +error out, rather than trying to muddle through and possibly generating +incorrect output. + +A changelog parser may not interact with the user at all. + +=head1 NOTES + +All B<Parser Options> except for B<-v> are only supported +since dpkg 1.14.16. + +Short option parsing with non-bundled values available only since dpkg 1.18.0. + +=head1 ENVIRONMENT + +=over + +=item B<DPKG_COLORS> + +Sets the color mode (since dpkg 1.18.5). +The currently accepted values are: B<auto> (default), B<always> and +B<never>. + +=item B<DPKG_NLS> + +If set, it will be used to decide whether to activate Native Language Support, +also known as internationalization (or i18n) support (since dpkg 1.19.0). +The accepted values are: B<0> and B<1> (default). + +=back + +=head1 FILES + +=over + +=item B<debian/changelog> + +The changelog file, used to obtain version-dependent information about +the source package, such as the urgency and distribution of an upload, +the changes made since a particular release, and the source version +number itself. + +=back + +=head1 SEE ALSO + +B<deb-changelog>(5). |