Report non-transient errors as errors, not as warnings

[apt.git] / doc / apt.8.xml

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
]>

<refentry>

 <refentryinfo>
   &apt-author.team;
   &apt-email;
   &apt-product;
   <!-- The last update date -->
   <date>2015-10-20T00:00:00Z</date>
 </refentryinfo>
 
 <refmeta>
   <refentrytitle>apt</refentrytitle>
   <manvolnum>8</manvolnum>
   <refmiscinfo class="manual">APT</refmiscinfo>
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>apt</refname>
    <refpurpose>command-line interface</refpurpose>
 </refnamediv>

 &synopsis-command-apt;

 <refsect1><title>Description</title>
   <para><command>apt</command> provides a high-level commandline interface for
      the package management system. It is intended as an end user interface and
      enables some options better suited for interactive usage by default
      compared to more specialized APT tools like &apt-get; and &apt-cache;.
   </para><para>
   Much like <command>apt</command> itself, its manpage is intended as an end
   user interface and as such only mentions the most used commands and options
   partly to not duplicate information in multiple places and partly to avoid
   overwhelming readers with a cornucopia of options and details.
   </para>

   <variablelist>
     <varlistentry><term><option>update</option> (&apt-get;)</term>
     <listitem><para><option>update</option> is used to download package
	   information from all configured sources. Other commands operate on
	   this data to e.g. perform package upgrades or search in and display
	   details about all packages available for installation.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>upgrade</option> (&apt-get;)</term>
     <listitem><para><option>upgrade</option> is used to install available
	   upgrades of all packages currently installed on the system from the
	   sources configured via &sources-list;. New packages will be
	   installed if required to statisfy dependencies, but existing
	   packages will never be removed. If an upgrade for a package requires
	   the remove of an installed package the upgrade for this package
	   isn't performed.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>full-upgrade</option> (&apt-get;)</term>
     <listitem><para><literal>full-upgrade</literal> performs the function of
	   upgrade but will remove currently installed packages if this is
	   needed to upgrade the system as a whole.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>install</option>, <option>remove</option>, <option>purge</option> (&apt-get;)</term>
     <listitem><para>Performs the requested action on one or more packages
	   specified via &regex;, &glob; or exact match. The requested action
	   can be overridden for specific packages by append a plus (+) to the
	   package name to install this package or a minus (-) to remove it.
     </para><para>
	   A specific version of a package can be selected for installation by
	   following the package name with an equals (=) and the version of the
	   package to select. Alternatively the version from a specific release can be
	   selected by following the package name with a forward slash (/) and
	   codename (&debian-stable-codename;, &debian-testing-codename;, sid …) or suite name (stable,
	   testing, unstable). This will also select versions from this release
	   for dependencies of this package if needed to satisfy the request.
     </para><para>
	   Removing a package removes all packaged data, but leaves usually
	   small (modified) user configuration files behind, in case the
	   remove was an accident. Just issuing an installation request for the
	   accidentally removed package will restore its function as before in
	   that case. On the other hand you can get rid of these leftovers
	   by calling <command>purge</command> even on already removed
	   packages. Note that this does not affect any data or configuration
	   stored in your home directory.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>autoremove</option> (&apt-get;)</term>
     <listitem><para>
	   <literal>autoremove</literal> is used to remove packages that were
	   automatically installed to satisfy dependencies for other packages
	   and are now no longer needed as dependencies changed or the package(s)
	   needing them were removed in the meantime.
     </para><para>
	   You should check that the list does not include applications you have
	   grown to like even though they were once installed just as a
	   dependency of another package. You can mark such a package as manually
	   installed by using &apt-mark;. Packages which you have installed explicitly
	   via <command>install</command> are also never proposed for automatic removal.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>search</option> (&apt-cache;)</term>
     <listitem><para><option>search</option> can be used to search for the given
	   &regex; term(s) in the list of available packages and display
	   matches.  This can e.g. be useful if you are looking for packages
	   having a specific feature.  If you are looking for a package
	   including a specific file try &apt-file;.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>show</option> (&apt-cache;)</term>
     <listitem><para>Show information about the given package(s) including
	   its dependencies, installation and download size, sources the
	   package is available from, the description of the packages content
	   and much more. It can e.g. be helpful to look at this information
	   before allowing &apt; to remove a package or while searching for
	   new packages to install.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>list</option> (work-in-progress)</term>
     <listitem><para><option>list</option> is somewhat similar to <command>dpkg-query --list</command>
	   in that it can display a list of packages satisfying certain
	   criteria.  It supports &glob; patterns for matching package names as
	   well as options to list installed (<option>--installed</option>),
	   upgradeable (<option>--upgradeable</option>) or all available
	   (<option>--all-versions</option>) versions.
     </para></listitem>
     </varlistentry>

     <varlistentry><term><option>edit-sources</option> (work-in-progress)</term>
     <listitem><para><literal>edit-sources</literal> lets you edit
	   your &sources-list; files in your preferred texteditor while also
	   providing basic sanity checks.
     </para></listitem>
     </varlistentry>


   </variablelist>
 </refsect1>

 <refsect1><title>Script Usage and Differences from Other APT Tools</title>
  <para>
   The &apt; commandline is designed as an end-user tool and it may
   change behavior between versions. While it tries not to break
   backward compatibility this is not guaranteed either if a change
   seems beneficial for interactive use.
  </para><para>
   All features of &apt; are available in dedicated APT tools like &apt-get;
   and &apt-cache; as well.  &apt; just changes the default value of some
   options (see &apt-conf; and specifically the Binary scope). So you should
   prefer using these commands (potentially with some additional options
   enabled) in your scripts as they keep backward compatibility as much as possible.
   </para>
 </refsect1>

 <refsect1><title>See Also</title>
   <para>&apt-get;, &apt-cache;, &sources-list;,
   &apt-conf;, &apt-config;,
   The APT User's guide in &guidesdir;, &apt-preferences;, the APT Howto.</para>
 </refsect1>

 <refsect1><title>Diagnostics</title>
   <para><command>apt</command> returns zero on normal operation, decimal 100 on error.</para>
 </refsect1>
 &manbugs;
</refentry>