review apt(8) manpage

[apt.git] / doc / apt-mark.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.moconnor;
   &apt-author.team;
   &apt-email;
   &apt-product;
   <!-- The last update date -->
   <date>2015-09-25T00:00:00Z</date>
 </refentryinfo>
 
 <refmeta>
   <refentrytitle>apt-mark</refentrytitle>
   <manvolnum>8</manvolnum>
   <refmiscinfo class="manual">APT</refmiscinfo>
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>apt-mark</refname>
    <refpurpose>show, set and unset various settings for a package</refpurpose>
 </refnamediv>

 &synopsis-command-apt-mark;

 <refsect1><title>Description</title>
    <para><command>apt-mark</command> can be used as a unified frontend to set
       various settings for a package like marking a package as being
       automatically/manually installed or changing <command>dpkg</command>
       selections such as hold, install, deinstall and purge which are respected
       e.g. by <command>apt-get dselect-upgrade</command> or <command>aptitude</command>.
   </para>
 </refsect1><refsect1><title>Automatically and manually installed packages</title>
   <para>
     When you request that a package is installed, and as a result
     other packages are installed to satisfy its dependencies, the
     dependencies are marked as being automatically installed, while
     package you installed explicitly is marked as manually installed.
     Once a automatically installed package is no longer depended on
     by any manually installed package it is considered no longer needed
     and e.g. <command>apt-get</command> or <command>aptitude</command>
     will at least suggest removing them.
   </para>
   <variablelist>
     <varlistentry><term><option>auto</option></term>
	 <listitem><para><literal>auto</literal> is used to mark a
     package as being automatically installed, which will cause the
     package to be removed when no more manually installed packages
     depend on this package.
       </para></listitem>
     </varlistentry>

     <varlistentry><term><option>manual</option></term>
	 <listitem><para><literal>manual</literal> is used to mark a
     package as being manually installed, which will prevent the
     package from being automatically removed if no other packages
     depend on it.
       </para></listitem>
     </varlistentry>

       <varlistentry><term><option>showauto</option></term>
	 <listitem><para><literal>showauto</literal> is used to print a
     list of automatically installed packages with each package on a new line.
     All automatically installed packages will be listed if no package is given.
     If packages are given only those which are automatically installed will be shown.
       </para></listitem>
     </varlistentry>

       <varlistentry><term><option>showmanual</option></term>
	 <listitem><para><literal>showmanual</literal> can be used in
     the same way as <literal>showauto</literal> except that it will print
     a list of manually installed packages instead.
       </para></listitem>
     </varlistentry>
   </variablelist>

   <refsect2><title>Options</title>
     <variablelist>
       <varlistentry>
	 <term><option>-f=&synopsis-param-filename;</option></term>
	 <term><option>--file=&synopsis-param-filename;</option></term>
	 <listitem><para>
	   Read/Write package stats from the filename given with the parameter
	   &synopsis-param-filename; instead of from the default location, which
	   is <filename>extended_status</filename> in the directory defined
	   by the Configuration Item: <literal>Dir::State</literal>.
	 </para></listitem>
       </varlistentry>
     </variablelist>
   </refsect2>

 </refsect1><refsect1><title>Prevent changes for a package</title>
   <variablelist>
     <varlistentry><term><option>hold</option></term>
	 <listitem><para><literal>hold</literal> is used to mark a
     package as held back, which will prevent the package from being
     automatically installed, upgraded or removed.
       </para></listitem>
     </varlistentry>

     <varlistentry><term><option>unhold</option></term>
	 <listitem><para><literal>unhold</literal> is used to cancel a
     previously set hold on a package to allow all actions again.
       </para></listitem>
     </varlistentry>

     <varlistentry><term><option>showhold</option></term>
	 <listitem><para><literal>showhold</literal> is used to print a list
     of packages on hold in the same way as for the other show commands.
       </para></listitem>
     </varlistentry>
   </variablelist>
 </refsect1><refsect1><title>Shedule packages for install, remove and purge</title>
 <para>
    Some frontends like <command>apt-get dselect-upgrade</command> can be used to
    apply previously sheduled changes to the install state of packages. Such changes
    can be sheduled with the <option>install</option>, <option>remove</option>
    (also known as <option>deinstall</option>) and <option>purge</option> commands.
    Packages with a specific selection can be displayed with <option>showinstall</option>,
    <option>showremove</option> and <option>showpurge</option> respectively.
    More information about these so called dpkg selections can be found in &dpkg;.
 </para>
 </refsect1>

 <refsect1><title>Options</title>
   <variablelist>
     &apt-commonoptions;
   </variablelist>
 </refsect1>

 <refsect1><title>Files</title>
   <variablelist>
	&file-extended_states;
   </variablelist>
 </refsect1>

 <refsect1><title>See Also</title>
    <para><phrase>&apt-get;,&aptitude;,&apt-conf;</phrase></para>
 </refsect1>

 <refsect1><title>Diagnostics</title>
   <para><command>apt-mark</command> returns zero on normal operation, non-zero on error.</para>
 </refsect1>

 &manbugs;
 
</refentry>