SYNOPSIS

apt-file [options] search pattern

apt-file [options] show package

DESCRIPTION

apt-file is a command line tool for searching files in packages for the APT package management system.

Some actions are required to run the search:

find

Alias for search.

list

List the contents of a package. This action is very close to the dpkg -L command except the package does not need to be installed or fetched.

By default, the list action interprets its pattern as if --fixed-string was specified.

search

Search in which package a file is included. A list of all packages containing the pattern pattern is returned.

Since Contents files does not contain directories, the pattern must match (part of a) file name.

By default, the search action interprets its pattern as if --substring-string was specified.

show

Alias for list.

update

Deprecated action that just calls ``apt update''.

OPTIONS

The following options are available:

-a, --architecture architecture[,...]

This option is useful if you search a package for a different architecture from the one installed on your system.

It can be a comma-separated list for searching on multiple architectures.

-c, --config-file APT config-file

Configuration File; Specify a configuration file to use. The program will read the default configuration file and then this configuration file. If configuration settings need to be set before the default configuration files are parsed specify a file with the APT_CONFIG environment variable. See apt.conf(5) for syntax information.

-D, --from-deb

Use contents of the given .deb archives(s) as patterns. Useful for searching for file conflicts with other packages. Implies -F.

-f, --from-file

Read patterns from the given file(s), one per line. Use - 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.

-F, --fixed-string

Do not expand search pattern with generic characters at pattern's start and end.

This is default for show and list actions.

--index-names type[,...], -I type[,...]

Only search indexes of the given name(s). The name(s) must match one or more of the names used in the APT configuration (minus leading ``Contents-''). Example if the configuration has the following snippets:

 Acquire::IndexTargets::deb::Contents-deb { ... };
 Acquire::IndexTargets::deb-src::Contents-dsc { ... };
 Acquire::IndexTargets::deb::Contents-udeb { ... };

Then, apt-file will recognise ``deb'', ``dsc'' and ``udeb'' as index names.

-i, --ignore-case

Ignore case when searching for pattern.

-l, --package-only

Only display package name; do not display file names.

-o, --option APT::Option=Value

Set a Configuration Option; This will set an arbitrary configuration option. The syntax is -o APT::Option=Value. -o and --option can be used multiple times to set different options.

--substring-match

Match if the given search pattern is a substring of a path or package.

This is default for search and find actions.

-v, --verbose

Run apt-file in verbose/debug mode.

-x, --regexp

Treat pattern as a (perl) regular expression. See perlreref(1) for details. Without this option, pattern is treated as a literal string to search for.

Be advised that this option can be rather slow. If performance is an issue, consider giving apt-file non-regex pattern matching too much and pipe the output to perl -ne '/<pattern-here>/'. This enables apt-file to use more optimizations and leaves less work to the ``slower'' regex.

-h, --help

Display a short help screen.

CONFIGURATION FILES

The apt-file command relies on the APT configuration. Notably, the default configuration makes apt fetch Contents files by default during a call to apt update.

For information on how to configure APT to fetch more or fewer Contents files, please refer to /usr/share/doc/apt-file/README.md.gz.

The following files are notably interesting:

/etc/apt/apt-file.conf

Note this path is actually configurable by changing the value of the APT configuration called ``Dir::Etc::apt-file-main''. The listed value is merely the default value of that option.

If this file is present, apt-file will read this file after all default APT configuration files. Any config file -c or option (-o) will be evaluated after this file (and can override options set in it).

The file will also be passed on to all APT tools called by apt-file.

/etc/apt/apt.conf.d/50apt-file.conf

Chooses which Contents files to download. Note that apt-file recognises only ``Acquire'' targets that starts with ``Contents-''.

Special configurations similar to apt-file 2

Here are some apt-file 2 related work flows and how to (almost) emulate them with apt-file 3. They are documented as a starting point for people, who are attached to these.

The emulation may not be perfect for you out of the box. Patches are welcome to keep the examples updated as long as the examples remain ``trivial''.

• Only make apt-file update fetch Contents files

  If you are accustomed to apt update not fetching Contents files, then you can run /usr/share/doc/apt-file/examples/apt-file-2-update.sh. This script will configure apt and apt-file accordingly after best effort.

  Please read the resulting /etc/apt/apt-file.conf.

• Creating/using ``user'' caches

  Previous versions of apt-file had a ``--cache'' option, which could be used to denote a directory to store the Contents files. This can be emulated by doing:

    # Setup
    $ mkdir -p ~/.cache/apt-file ~/.config
    $ touch ~/.cache/apt-file/dpkg-status
    $ sed '/^Dir::State/ d; /^Dir::Cache/ d;' \
      /usr/share/doc/apt-file/examples/apt-file.conf \
      > ~/.config/apt-file.conf
    $ cat <<EOF >> ~/.config/apt-file.conf
  Dir::State "$HOME/.cache/apt-file";
  Dir::Cache "$HOME/.cache/apt-file";
  Dir::State::status "$HOME/.cache/apt-file/dpkg-status";
  EOF
    # Update the cache
    $ apt-file -c ~/.config/apt-file.conf update
    # Search using the cache
    $ apt-file -c ~/.config/apt-file.conf show apt-file
    # Removal of the cache + config
    $ rm -fr ~/.cache/apt-file ~/.config/apt-file.conf
  

  (You will probably want to add an alias apt-file in your ~/.bashrc)

  Please read the resulting ./apt-file-user-cache.conf.