123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605 |
- <!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
- <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
- <!ENTITY docbook "<productname>DocBook</productname>">
- ]>
- <!-- vim:set fileencoding=utf-8 et ts=4 sts=4 sw=4: -->
- <!-- Manual page for debchanges, DocBook source file
- (C) 2000 Matt Zimmerman <mdz@debian.org>
- Based on the example page docbook-to-man.sgml from docbook-to-man
- -->
- <refentry>
- <docinfo>
- <address><email>mdz@debian.org</email></address>
- <author>
- <firstname>Matt</firstname>
- <surname>Zimmerman</surname>
- </author>
- <date>2016-04-23</date>
- </docinfo>
- <refmeta>
- <refentrytitle>apt-listchanges</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>apt-listchanges</refname>
- <refpurpose>Show new changelog entries from Debian package archives</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>apt-listchanges</command>
- <group choice=opt>
- <arg rep=repeat><replaceable>options</replaceable></arg>
- </group>
- <group choice=req>
- <arg><option>--apt</option></arg>
- <arg rep=repeat><replaceable>package.deb</replaceable></arg>
- </group>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>DESCRIPTION</title>
- <para><command>apt-listchanges</command> is a tool to show what
- has been changed in a new version of a Debian package, as
- compared to the version currently installed on the
- system.</para>
- <para>It does this by extracting the relevant entries from both the
- NEWS.Debian and changelog<optional>.Debian</optional> files, usually found in
- <filename>/usr/share/doc/</filename><replaceable>package</replaceable>,
- from Debian package archives.
- </para>
- <para>
- Given a set of filenames as arguments (or read from apt when
- using <option>--apt</option>),
- <command>apt-listchanges</command> will scan the files (assumed
- to be Debian package archives) for the relevant changelog
- entries, and display them all in a summary grouped by source package.
- The groups are sorted by the urgency of the most urgent change,
- and than by the package name. Changes within each package group are
- displayed in the order of their apperance in the changelog files, i.e.
- starting from the latest to the oldest; the
- <option>--reverse</option> option can be used to alter this order.
- </para>
- </refsect1>
- <refsect1>
- <title>OPTIONS</title>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM><option>--apt</option></TERM>
- <LISTITEM>
- <PARA>Read filenames from a specially-formatted pipeline (as
- provided by apt), rather than from command line arguments,
- and honor certain apt-specific options in the config
- file. This pipeline must be in "version 2" format,
- specified in the apt configuration.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><option>-v, --verbose</option></TERM>
- <LISTITEM>
- <PARA>Display additional (usually unwanted) information.
- For instance, print a message when a package of the same
- or older version is to be installed, or when a package is
- to be newly installed.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><option>-f, --frontend</option></TERM>
- <LISTITEM>
- <PARA>
- Select which frontend to use to display information to the
- user. Current frontends include:
- </PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>pager</TERM>
- <LISTITEM>
- <PARA>
- Uses <citerefentry><refentrytitle>sensible-pager</refentrytitle>
- <manvolnum>1</manvolnum></citerefentry> command to
- display output. The command uses PAGER environment
- variable to choose your favourite pager. The "pager" option
- may be specified in the configuration file to select a specific pager for
- use with apt-listchanges.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <varlistentry>
- <term>browser</term>
- <listitem>
- <para>
- Displays an HTML-formatted changelog with hyperlinks for bugs
- and email addresses using the <citerefentry>
- <refentrytitle>sensible-browser</refentrytitle><manvolnum>1</manvolnum>
- </citerefentry> command that examines BROWSER environment variable
- to choose your favourite browser. The "browser" option may be
- specified in the configuration file to select a specific browser for
- use with apt-listchanges.
- </para>
- </listitem>
- </varlistentry>
- <VARLISTENTRY>
- <TERM>xterm-pager</TERM>
- <LISTITEM>
- <PARA>
- Uses your favorite pager to display output, but does
- so in an xterm (using the x-terminal-emulator
- alternative) in the background. This allows you
- to go on with the upgrade if you like, and continue
- to browse the changelogs. You can override the
- terminal emulator to be used with the "xterm"
- configuration option.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <varlistentry>
- <term>xterm-browser</term>
- <listitem>
- <para>
- The logical combination of xterm-pager and browser.
- Only appropriate for text-mode browsers.
- </para>
- </listitem>
- </varlistentry>
- <VARLISTENTRY>
- <TERM>text</TERM>
- <LISTITEM>
- <PARA>
- Dumps output to stdout, with no pauses.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>mail</TERM>
- <LISTITEM>
- <PARA>
- Sends mail to the address specified with
- --email-address, and does not display changelogs.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>gtk</TERM>
- <LISTITEM>
- <PARA>
- Spawns a gtk window to display the changelogs. Needs
- python3-gi to be installed.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>none</TERM>
- <LISTITEM>
- <PARA>
- Does nothing. Can be used to prevent
- apt-listchanges from running when configured to run
- automatically from apt.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
- <para>
- Please note that apt-listchanges will try to switch to an unprivileged
- user before spawning commands in "browser", "xterm-browser",
- and "xterm-pager" frontends. However this currently does not apply
- to the "pager" frontend. See also "ENVIRONMENT VARIABLES" below.
- </para>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--email-address=<replaceable>address</replaceable></OPTION></TERM>
- <LISTITEM>
- <PARA>
- In addition to displaying it, mail a copy of the changelog
- data to the specified address. To only mail changelog
- entries, use this option with the special frontend 'mail'.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--email-format={text|html}</OPTION></TERM>
- <LISTITEM>
- <PARA>
- If sending mail copies is enabled (see <option>--email-address</option> above),
- this option selects whether the mail should be sent
- as an old good plain text data (which is the default behavior),
- or as html data with clickable links, which might be more
- convenient for people using graphical mail clients.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>-c, --confirm</OPTION></TERM>
- <LISTITEM>
- <PARA>
- Once changelogs have been displayed, ask the user whether
- or not to proceed. If the user chooses not to proceed, a
- nonzero exit status will be returned, and apt will abort.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>-a, --show-all</OPTION></TERM>
- <LISTITEM>
- <PARA>
- Rather than trying to display changelog entries that are
- newer than the currently installed version of the package,
- simply display all changelog entries for all packages.
- This is useful for viewing the entire changelog of a .deb
- before extracting it.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--save-seen=<replaceable>file</replaceable></OPTION></TERM>
- <LISTITEM>
- <PARA>
- This option will cause apt-listchanges to keep track of
- the last version of a package for which changelogs have
- been displayed, to avoid redisplaying the same changelogs
- in a future invocation. The database is stored in the
- named file. Specify 'none' to disable this feature.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--dump-seen</OPTION></TERM>
- <LISTITEM>
- <PARA>
- Display the contents of the seen database to standard output
- as a list of lines consising of source package name and its
- latest seen version, separated by space. This option requires
- the path to the seen database to be known: please either specify
- it using <option>--save-seen</option> option or pass
- <option>--profile=apt</option> option to have it read from the
- configuration file.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--since=<replaceable>version</replaceable></OPTION></TERM>
- <LISTITEM>
- <PARA>
- This option will cause apt-listchanges to show the entries later
- than the specified version. With this option, the only other
- argument you can pass is the path to a .deb file.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--which={news|changelogs|both}</OPTION></TERM>
- <LISTITEM>
- <PARA>
- This option selects whether news (from NEWS.Debian et
- al.), changelogs (from changelog.Debian et al.) or both
- should be displayed. The default is to display only news.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>--help</OPTION></TERM>
- <LISTITEM>
- <PARA>
- Displays syntax information.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM><OPTION>-h, --headers</OPTION></TERM>
- <LISTITEM>
- <PARA>
- These options will cause apt-listchanges to insert a
- header before each package's changelog showing the name of
- the package, and the names of the binary packages which
- are being upgraded (if there is more than one, or it
- differs from the source package name).
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <varlistentry>
- <term><option>--debug</option></term>
- <listitem>
- <para>Display some debugging information
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--profile=<replaceable>name</replaceable></option></term>
- <listitem>
- <para>Select an option profile.
- <replaceable>name</replaceable> corresponds to a section in
- <filename>/etc/apt/listchanges.conf</filename>. The default
- when invoked from apt is "apt", and "cmdline" otherwise.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--reverse</option></term>
- <listitem>
- <para>
- Show the changelog entries in reverse order.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--ignore-apt-assume</option>, <option>--ignore-debian-frontend</option></term>
- <listitem>
- <para>
- Disable forcing non-interactive frontend in some of the cases described in the
- "AUTOMATIC FRONTEND OVERRIDE" section below.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--select-frontend</option></term>
- <listitem>
- <para>
- Choose frontend interactively. This option is mainly for testing purposes,
- please do not use it.
- </para>
- </listitem>
- </varlistentry>
- </VARIABLELIST>
- </refsect1>
- <refsect1>
- <title>AUTOMATIC FRONTEND OVERRIDE</title>
- <para>
- For a better integration with existing package management tools,
- <command>apt-listchanges</command> tries to detect if package upgrades
- are done in a non-interactive way, and automatically switches its frontend
- to 'text' when <emphasis>any</emphasis> of the following conditions is satisfied:
- <itemizedlist mark='opencircle'>
- <listitem>
- <para>the standard output is not connected to terminal;</para>
- </listitem>
- <listitem>
- <para>the <option>--quiet</option> (<option>-q</option>) option is given
- to <citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum>
- </citerefentry> (or <citerefentry><refentrytitle>aptitude</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry>); note however that when the option
- is used more than once, apt-listchanges switches the frontend to 'mail';</para>
- </listitem>
- <listitem>
- <para>the <option>--assume-yes</option> (<option>-y</option>) option is given
- to <citerefentry><refentrytitle>apt-get</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry>);</para>
- </listitem>
- <listitem>
- <para>the <envar>DEBIAN_FRONTEND</envar> environment variable is set to
- "noninteractive", and <envar>APT_LISTCHANGES_FRONTED</envar> is not set.</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- For backward compatibility purposes the last two of the above checks can be disabled
- either with "ignore_apt_assume=true" or "ignore_debian_frontend=true" configuration file
- entries (see "CONFIGURATION FILE" below) or by using the command line
- options: <option>--ignore-apt-assume</option> or <option>--ignore-debian-frontend</option>.
- </para>
- <para>
- Please also note that the "mail" frontend is already non-interactive one, so it is never
- switched to the "text" frontend.
- </para>
- <para>
- Additionally <command>apt-listchanges</command> overrides X11-based frontends
- ("gtk", "xterm-pager", "xterm-browser") with "pager" (or "browser" in case
- of "xterm-browser") when the environment variable <envar>DISPLAY</envar>
- is not set.
- </para>
- </refsect1>
- <refsect1>
- <title>CONFIGURATION FILE</title>
- <para>
- <command>apt-listchanges</command> reads its configuration from the
- <filename>/etc/apt/listchanges.conf</filename>. The file consists of
- <replaceable>sections</replaceable> with names enclosed in the square
- brackets. Each section should contain lines in the
- <replaceable>key</replaceable>=<replaceable>value</replaceable> format.
- Lines starting with the "#" sign are treated as comments and ignored.
- </para>
- <para>
- <replaceable>Section</replaceable> is a name of profile that can be
- used as parameter of the <option>--profile</option> option.
- </para>
- <para>
- <replaceable>Key</replaceable> is a name of some command-line option
- (except for <option>--apt</option>, <option>--profile</option>,
- <option>--help</option>) with the initial hyphens removed, and the
- remaining hyphens translated to underscores, for example: "email_format"
- or "save_seen".
- </para>
- <para>
- <replaceable>Value</replaceable> represents the value of the corresponding
- option. For command-line options that do not take argument, like "confirm"
- or "header", the <replaceable>value</replaceable> should be set either to
- "1", "yes", "true", and "on" in order to enable the option, or to "0",
- "no", "false", and "off" to disable it.
- </para>
- <para>
- Additionally <replaceable>key</replaceable> can be one of the following
- keywords: "browser", "pager" or "xterm". The <replaceable>value</replaceable>
- of such configuration entry should be the name of an appropriate command,
- eventually followed by its arguments, for example: "pager=less -R".
- </para>
- <example>
- <title>Example configuration file</title>
- <programlisting>
- [cmdline]
- frontend=pager
- [apt]
- frontend=xterm-pager
- email_address=root
- confirm=1
- [custom]
- frontend=browser
- browser=mozilla
- </programlisting>
- </example>
- <para>The above configuration file specifies that in
- command-line mode, the default frontend should be "pager".
- In apt mode, the xterm-pager frontend is default, a copy
- of the changelogs (if any) should be emailed to root, and
- apt-listchanges should ask for confirmation. If
- apt-listchanges is invoked with --profile=custom, the
- browser frontend will be used, and invoke mozilla.</para>
- </refsect1>
- <refsect1>
- <title>ENVIRONMENT</title>
- <variablelist>
- <varlistentry>
- <term>APT_LISTCHANGES_FRONTEND</term>
- <listitem><para>Frontend to use</para></listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>APT_LISTCHANGES_USER, SUDO_USER, USERNAME</term>
- <listitem><para>The value of the first existing of the above variables
- will be used as the name of user to switch to when running
- commands spawned by the "browser", "xterm-browser",
- and "xterm-pager" frontends if <command>apt-listchanges</command> is
- started by a privileged user</para></listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>DEBIAN_FRONTEND</term>
- <listitem><para>If set to "noninteractive", then it can force
- <command>apt-listchanges</command> to use non-interactive frontend,
- see the "AUTOMATIC FRONTEND OVERRIDE" section for details.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>BROWSER</term>
- <listitem><para>Used by
- the browser frontend, should be set to a command expecting a
- file: URL for an HTML file to display.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>PAGER</term>
- <listitem><para>Used by the pager frontend</para></listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>APT_HOOK_INFO_FD</term>
- <listitem><para>File descriptor to read package names from in
- the <option>--apt</option> mode. (Apt is expected to set
- this variable to a proper file descriptor numer).</para></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>FILES</title>
- <variablelist>
- <varlistentry>
- <term>/etc/apt/listchanges.conf</term>
- <listitem><para>Configuration file</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>/etc/apt/apt.conf.d/20listchanges</term>
- <listitem><para>File used for registering apt-listchanges into apt system</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>/var/lib/apt/listchanges.db</term>
- <listitem><para>Database used for save-seen</para></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>AUTHOR</title>
- <PARA>
- apt-listchanges was written by Matt Zimmerman
- <mdz@debian.org>
- </PARA>
- </refsect1>
- <refsect1>
- <title>SEE ALSO</title>
- <para>
- <citerefentry><refentrytitle>sensible-pager</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sensible-browser</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>aptitude</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- </para>
- </refsect1>
- </refentry>
- <!-- Keep this comment at the end of the file
- Local variables:
- mode: sgml
- sgml-omittag:t
- sgml-shorttag:t
- sgml-minimize-attributes:nil
- sgml-always-quote-attributes:t
- sgml-indent-step:2
- sgml-indent-data:t
- sgml-parent-document:nil
- sgml-default-dtd-file:nil
- sgml-exposed-tags:nil
- sgml-local-catalogs:nil
- sgml-local-ecat-files:nil
- End:
- -->
|