<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
  <refentryinfo>
    <address>
      <email>sjg@debian.org</email>
    </address>
    <author>
      <firstname>Sebastien</firstname>
      <surname>Gross</surname>
      <othername>J.</othername>
    </author>
    <date>May 2003</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>apt-file</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>apt-file</refname>
    <refpurpose>
      APT package searching utility -- command-line interface
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>apt-file</command>
      <arg><option>options</option></arg>
      <arg>action</arg>
      <arg>pattern</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>apt-file</command>
      <option> -f</option>
      <arg><option>options</option></arg>
      <option> search</option>
      <arg>file ...</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>apt-file</command>
      <option> -D</option>
      <arg><option>options</option></arg>
      <option> search</option>
      <arg>binary-packet.deb ...</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para><command>apt-file</command> is a command line tool for
      searching files in packages for the APT package management system.</para>
    <para>Some actions are required to run the search:</para>
    <variablelist>

      <varlistentry>
	<term>find</term>
	<listitem>
	  <para>
	    Alias for <option>search</option>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>list</term>
	<listitem>
	  <para>
	    List the contents of a package matching the
	    <option>pattern</option> pattern. This action is very
	    close to the <command>dpkg -L</command> command except the
	    package does not need to be installed or fetched.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>purge</term>
	<listitem>
	  <para>
	    remove all <filename>Contents-*</filename>
	    files from the cache directory.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>search</term>
	<listitem>
	  <para>
	    Search in which package a file is included. A list of all
	    packages containing the <option>pattern</option> pattern
	    is returned.
	  </para>
	  <para>
	    apt-file will only search for filenames, not directory names.
	    This is due to the format of the Contents files it searches.
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>show</term>
	<listitem>
	  <para>
	    Alias for <option>list</option>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>update</term>
	<listitem>
	  <para>
	    Resynchronize the package contents from their sources. The
	    lists of the contents of packages are fetched from the location(s)
	    specified in
	    <filename>/etc/apt/sources.list</filename>. This command
	    attempts to fetch the
	    <filename>Contents-&lt;ARCH&gt;.gz</filename> files from
	    remote sources. For downloading these uses either the curl or
	    wget commands as specified in <filename>apt-file.conf</filename>.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <variablelist>

      <varlistentry>
	<term>
	  <option>-a, --architecture</option>
	  architecture
	</term>
	<listitem>
	  <para>
	  Sets architecture to <literal>architecture</literal>. This
	  option is useful if you search a package for a different
	  architecture from the one installed on your system.
	  It determines how the <literal>$ARCH</literal> variable
	  in sources.list is expanded (but it does not influence
	  the search in any other way).
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-c, --cache</option> <literal>cache-directory</literal>
	</term>
	<listitem>
	  <para>
	    Sets the cache directory to <filename>cache-directory</filename>
	    instead of its default. If executed as non-root user, the default
	    is <filename>$HOME/.cache/apt-file</filename> with fall-back to
	    <filename>/var/cache/apt/apt-file</filename>. The latter is also
	    the default if apt-file is called as root.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-d, --cdrom-mount</option> <literal>cdrom-mount-point</literal>
	</term>
	<listitem>
	  <para>
Use <literal>cdrom-mount-point</literal> instead of
<command>apt</command>'s.
</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-D, --from-deb</option>
	</term>
	<listitem>
	  <para>
	    Use contents of the given .deb archives(s) as patterns.
	    Useful for searching for file conflicts with other packages.
	    Implies <option>-F</option>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-f, --from-file</option>
	</term>
	<listitem>
	  <para>
	    Read patterns from the given file(s), one per line.
	    Use <literal>-</literal> as filename for stdin.
	    If no files are given, then the list will be read from stdin.
	    This is much faster than invoking apt-file many times.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-F, --fixed-string</option>
	</term>
	<listitem>
	  <para>
	    Do not expand search pattern with generic characters at
	    pattern's start and end.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-i, --ignore-case</option>
	</term>
	<listitem>
	  <para>Ignore case when searching for <literal>pattern</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-l, --package-only</option>
	</term>
	<listitem>
	  <para>
	    Only display package name; do not display file names.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-N, --non-interactive</option>
	</term>
	<listitem>
	  <para>
	  Skip schemes that are listed in the <literal>interactive</literal> line in
	  <filename>apt-file.conf</filename>.
	  This is useful if you want to call 'apt-file update' in cron jobs and skip all
	  schemes that may require user input.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-s, --sources-list</option>
	  sources.list
	</term>
	<listitem>
	  <para>
	    Sets the <filename>sources.list</filename> file to a
	    different value from its default
	    <filename>/etc/apt/sources.list</filename>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-v, --verbose</option>
	</term>
	<listitem>
	  <para>
	    Run <command>apt-file</command> in verbose mode.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-x, --regexp</option>
	</term>
	<listitem>
	  <para>
	    Treat <literal>pattern</literal> as a (perl) regular expression. See
	    <command>perlreref</command>(1) for details. Without this option,
	    <literal>pattern</literal> is treated as a literal string to search
	    for.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-y, --dummy</option>
	</term>
	<listitem>
	  <para>
	    Run in dummy mode (no action).
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <option>-h, --help</option>
	</term>
	<listitem>
	  <para>Display a short help screen.</para>
	</listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>CONFIGURATION FILE</title>
    <para>
      The <command>apt-file</command> configuration file can
      be found in <filename>/etc/apt/apt-file.conf</filename>.
    </para>
    <para>
      A string expansion is done on several values. See the <literal>string
	expansion</literal> section.
    </para>
    <variablelist>

      <varlistentry>
	<term>destination</term>
	<listitem>
	  <para>
	    This variable describes how cached files will be named.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>http | ftp | ssh | rsh | file | cdrom</term>
	<listitem>
	  <para>
	    Defines the commands used to fetch files.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
    <refsect2>
      <title>String expansion</title>

      <para>
	A <filename>sources.list</filename> entry is defined as:
	<screen>
	  deb uri dist component1 component2 ...
	</screen>
	A <literal>uri</literal> is defined as:
	<screen>
	  proto:/[/][user[:password]@]host[:port][/path]
	</screen>
      </para>

      <variablelist>
	<varlistentry>
	  <term>&lt;host&gt;</term>
	  <listitem>
	    <para>replace with the hostname</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;port&gt;</term>
	  <listitem>
	    <para>replace with the port number</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;uri&gt;</term>
	  <listitem>
	    <para>replace with full uri</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;path&gt;</term>
	  <listitem>
	    <para>
	      replace with full path (relative to / on the host)
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;dist&gt;</term>
	  <listitem>
	    <para>replace with distribution name</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;comp&gt;</term>
	  <listitem>
	    <para>replace with component name</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;cache&gt;</term>
	  <listitem><para>replace with cache directory</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;dest&gt;</term>
	  <listitem>
	    <para>
	      replace with <literal>destination</literal> expanded
	      value.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>&lt;cdrom&gt;</term>
	  <listitem>
	    <para>
	      replace with <literal>cdrom-mount-point</literal>.
	    </para>
	  </listitem>
	</varlistentry>

      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>BUGS</title>
    <para>The cdrom backend has not been tested.</para>
    <para>
      Non-release lines in sources.list are not handled by apt-file.
    </para>
    <para>
     There is only one Contents file per distribution that contains all
     components (i.e. main, contrib, and non-free). Threrefore, apt-file will
     display search results from all components, even if not all components
     are included in the sources.list file.
    </para>
    <para>
     When a new line has been added to the sources.list and apt-file update has
     not been run, apt-file does not print a warning message.
    </para>
    <para>
     Complex regular expressions that match the leading slash may not work
     correctly. As a workaround, try to pull the leading slash to the beginning
     of the regular expression. For example, use "/(usr/bin/vim|sbin/lvm)"
     instead of "/usr/bin/vim|/sbin/lvm".
    </para>
  </refsect1>

  <refsect1>
    <title>FILES</title>
    <variablelist>
      <varlistentry>
	<term><filename>/etc/apt/sources.list</filename></term>
	<listitem>
	  <para>Locations to fetch package contents from.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/apt/sources.list.d/</filename></term>
	<listitem>
	  <para>Directory with additional sources.list snippets</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/apt/apt-file.conf</filename></term>
	<listitem>
	  <para>
	    Configuration file for <command>apt-file</command>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <command>auto-apt</command>(1), <command>apt-cache</command>(8),
      <command>apt-cdrom</command>(8), <command>dpkg</command>(8),
      <command>dselect</command>(8),
      <filename>sources.list</filename>(5),
      <filename>apt.conf</filename>(5),
      <command>apt_preferences</command>(5).
    </para>
    <para>
      The APT users guide in
      <filename>/usr/share/doc/apt/</filename>
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
    <para>
      <command>apt-file</command> was written by Sebastien J. Gross
      <email>sjg@debian.org</email>.
    </para>
  </refsect1>

</refentry>