.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "APT-FILE 1"
.TH APT-FILE 1 "2017-01-23" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
apt\-file \-\- APT package searching utility \-\- command\-line interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBapt-file\fR [\fIoptions\fR] search \fIpattern\fR
.PP
\&\fBapt-file\fR [\fIoptions\fR] show \fIpackage\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBapt-file\fR is a command line tool for searching files in packages for
the \s-1APT\s0 package management system.
.PP
Some actions are required to run the search:
.IP "find" 4
.IX Item "find"
Alias for search.
.IP "list" 4
.IX Item "list"
List the contents of a package. This action is very close to the
\&\fBdpkg \-L\fR command except the package does not need to be installed or
fetched.
.Sp
By default, the \fBlist\fR action interprets its pattern as if
\&\fB\-\-fixed\-string\fR was specified.
.IP "search" 4
.IX Item "search"
Search in which package a file is included. A list of all packages
containing the pattern pattern is returned.
.Sp
Since Contents files does not contain directories, the pattern must
match (part of a) file name.
.Sp
By default, the \fBsearch\fR action interprets its pattern as if
\&\fB\-\-substring\-match\fR was specified.
.IP "show" 4
.IX Item "show"
Alias for list.
.IP "update" 4
.IX Item "update"
Deprecated action that just calls \*(L"apt update\*(R".
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options are available:
.IP "\-a, \-\-architecture \fIarchitecture[,...]\fR" 4
.IX Item "-a, --architecture architecture[,...]"
This option is useful if you search a package for a different
architecture from the one installed on your system.
.Sp
It can be a comma-separated list for searching on multiple
architectures.
.IP "\-c, \-\-config\-file \fI\s-1APT\s0 config-file\fR" 4
.IX Item "-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 \fB\s-1APT_CONFIG\s0\fR
environment variable. See \fIapt.conf\fR\|(5) for syntax information.
.Sp
The configuration file will be read relative to when it appears on the
command line and can overwrite options that appear before it.
.Sp
Note that the config file will also be passed to all \s-1APT\s0 tools called
by \fBapt-file\fR.
.IP "\-D, \-\-from\-deb" 4
.IX Item "-D, --from-deb"
Use contents of the given .deb archives(s) as patterns.  Useful for
searching for file conflicts with other packages.  Implies \-F.
.IP "\-f, \-\-from\-file" 4
.IX Item "-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.
.IP "\-\-filter\-origins \fIorigin[,...]\fR" 4
.IX Item "--filter-origins origin[,...]"
Only search indices from the listed origins (e.g. \*(L"Debian\*(R").
.Sp
This filter matches against the name listed in the \fIOrigin\fR field
from the Release file.
.Sp
If set to '*', this filter will be disabled (mostly useful for
overriding the setting in a configuration file)
.Sp
Alias of the \s-1APT\s0 config option: \fBapt\-file::Search\-Filter::Origin\fR
.IP "\-\-filter\-suites \fIsuite[,...]\fR" 4
.IX Item "--filter-suites suite[,...]"
Only search indices from the listed suites or codenames
(e.g. \*(L"unstable\*(R").
.Sp
This filter matches against the name listed in the \fICodename\fR and
\&\fISuite\fR fields from the Release file.  This means that either
\&\*(L"unstable\*(R" or \*(L"sid\*(R" will match Debian's unstable suite.
.Sp
If set to '*', this filter will be disabled (mostly useful for
overriding the setting in a configuration file)
.Sp
Alias of the \s-1APT\s0 config option: \fBapt\-file::Search\-Filter::Suite\fR
.IP "\-F, \-\-fixed\-string" 4
.IX Item "-F, --fixed-string"
Do not expand search pattern with generic characters at pattern's
start and end.
.Sp
This is default for \fBshow\fR and \fBlist\fR actions.
.IP "\-\-index\-names \fItype[,...]\fR, \-I \fItype[,...]\fR" 4
.IX Item "--index-names type[,...], -I type[,...]"
Only search indexes of the given name(s). If set to the special value
\&\fI\s-1ALL\s0\fR (case-sensitive), then all \fBapt-file\fR indices are searched.
.Sp
The name(s) must match one or more of the identifiers used in the \s-1APT\s0
configuration (minus leading \*(L"Contents\-\*(R").  Example if the
configuration has the following snippets:
.Sp
.Vb 8
\& Acquire::IndexTargets::deb::Contents\-deb { ... };
\& Acquire::IndexTargets::deb\-src::Contents\-dsc { ... };
\& Acquire::IndexTargets::deb::Contents\-udeb { ... };
\& Acquire::IndexTargets::deb::Contents\-deb\-legacy {
\&    # Explicitly named to "Contents\-deb"
\&    Identifier "Contents\-deb";
\&    ...;
\& };
.Ve
.Sp
Then, apt-file will recognise \*(L"deb\*(R", \*(L"dsc\*(R" and \*(L"udeb\*(R" as index names.
.Sp
This option defaults to the value of the \*(L"apt\-file::Index\-Names\*(R" apt
config option (or \*(L"deb\*(R" if omitted).
.IP "\-i, \-\-ignore\-case" 4
.IX Item "-i, --ignore-case"
Ignore case when searching for pattern.
.IP "\-l, \-\-package\-only" 4
.IX Item "-l, --package-only"
Only display package name; do not display file names.
.IP "\-o, \-\-option APT::Option=Value" 4
.IX Item "-o, --option APT::Option=Value"
Set a Configuration Option; This will set an arbitrary configuration
option. The syntax is \fB\-o APT::Option=Value\fR.  \fB\-o\fR and \fB\-\-option\fR
can be used multiple times to set different options.
.Sp
This option \fIcan\fR be used to overwrite other command line options
(e.g. \*(L"\-o apt\-file::Search\-Filter::Origin=Debian\*(R" is effectively the
same as \*(L"\-\-filter\-origins Debian\*(R").
.Sp
Note that the config options passed via this option will also be
passed to all \s-1APT\s0 tools called by \fBapt-file\fR.
.IP "\-\-substring\-match" 4
.IX Item "--substring-match"
Match if the given search \fIpattern\fR is a substring of a path or
package.
.Sp
This is default for \fBsearch\fR and \fBfind\fR actions.
.IP "\-v, \-\-verbose" 4
.IX Item "-v, --verbose"
Run apt-file in verbose/debug mode.
.IP "\-x, \-\-regexp" 4
.IX Item "-x, --regexp"
Treat pattern as a (perl) regular expression. See \fIperlreref\fR\|(1) for
details. Without this option, pattern is treated as a literal string
to search for.
.Sp
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 \fBperl \-ne '/<pattern\-here>/'\fR.  This enables
apt-file to use more optimizations and leaves less work to the
\&\*(L"slower\*(R" regex.
.IP "\-h, \-\-help" 4
.IX Item "-h, --help"
Display a short help screen.
.SH "CONFIGURATION FILES"
.IX Header "CONFIGURATION FILES"
The apt-file command relies on the \s-1APT\s0 configuration.  Notably, the
default configuration makes \fBapt\fR fetch Contents files by default
during a call to \fBapt update\fR.
.PP
For information on how to configure \s-1APT\s0 to fetch more or fewer
Contents files, please refer to
\&\fI/usr/share/doc/apt\-file/README.md.gz\fR.
.PP
The following files are notably interesting:
.IP "\fI/etc/apt/apt\-file.conf\fR" 4
.IX Item "/etc/apt/apt-file.conf"
Note this path is actually configurable by changing the value of the
\&\s-1APT\s0 configuration called \*(L"Dir::Etc::apt\-file\-main\*(R".  The listed value
is merely the default value of that option.
.Sp
If this file is present, \fBapt-file\fR will read this file \fIafter\fR all
default \s-1APT\s0 configuration files.  Any config file \fB\-c\fR or option
(\fB\-o\fR) will be evaluated \fIbefore\fR this file (and can override
options set in it).
.Sp
The file will also be passed on to all \s-1APT\s0 tools called by
\&\fBapt-file\fR.
.IP "\fI/etc/apt/apt.conf.d/50apt\-file.conf\fR" 4
.IX Item "/etc/apt/apt.conf.d/50apt-file.conf"
Chooses which Contents files to download.  Note that apt-file
recognises only \*(L"Acquire\*(R" targets that starts with \*(L"Contents\-\*(R".
.SS "Special configurations similar to apt-file 2"
.IX Subsection "Special configurations similar to apt-file 2"
Here are some \fBapt-file\fR 2 related work flows and how to (almost)
emulate them with \fBapt-file\fR 3.  They are documented as a \fIstarting
point\fR for people, who are attached to these.
.PP
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
\&\*(L"trivial\*(R".
.IP "\(bu" 4
Only make \fBapt-file update\fR fetch Contents files
.Sp
If you are accustomed to \fBapt update\fR \fInot\fR fetching Contents files,
then you can run
\&\fI/usr/share/doc/apt\-file/examples/apt\-file\-2\-update.sh\fR.  This script
will configure \fBapt\fR and \fBapt-file\fR accordingly after best effort.
.Sp
Please read the resulting \fI/etc/apt/apt\-file.conf\fR.
.IP "\(bu" 4
Creating/using \*(L"user\*(R" caches
.Sp
Previous versions of \fBapt-file\fR had a \*(L"\-\-cache\*(R" option, which could
be used to denote a directory to store the Contents files.  This can
be emulated by doing:
.Sp
.Vb 11
\&  # Setup
\&  $ mkdir \-p ~/.cache/apt\-file ~/.config
\&  $ touch ~/.cache/apt\-file/dpkg\-status
\&  $ sed \*(Aq/^Dir::State/ d; /^Dir::Cache/ d;\*(Aq \e
\&    /usr/share/doc/apt\-file/examples/apt\-file.conf \e
\&    > ~/.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
.Ve
.Sp
(You will probably want to add an alias apt-file in your \fI~/.bashrc\fR)
.Sp
Please read the resulting \fI./apt\-file\-user\-cache.conf\fR.
.SH "BUGS, QUIRKS"
.IX Header "BUGS, QUIRKS"
There are some known issues or \*(L"quirks\*(R" that are good to keep in mind.
.IP "\(bu" 4
The Contents files do \fBnot\fR include a leading slash on paths.  This
means that \fI/bin/ls\fR is listed as \fIbin/ls\fR in the Contents file.  If
you are looking for something in a top-level directory, it is often
better to omit the leading slash.
.Sp
The search algorithm will attempt to work around the leading slash,
but it will not work in all cases.  As a workaround, try to pull the
leading slash to the beginning of regular expressions.  For example,
use \*(L"/(?:usr/bin/vim|sbin/lvm)\*(R" instead of  \*(L"/usr/bin/vim|/sbin/lvm\*(R".
.IP "\(bu" 4
When a new line has been added to the sources.list and apt update
has not been run, apt-file does not print a warning message.
.IP "\(bu" 4
Not all \s-1APT\s0 repositories have Contents files.  Notably common install
media (CDs etc.) may omit them to conserve space.
.Sp
The default configuration by \fBapt-file\fR marks Contents files as
optional and will just silently fail to search in Contents files in
such repositories.
.SH "EXIT CODES"
.IX Header "EXIT CODES"
\&\fBapt-file\fR has the following defined exit codes, which can be used
for scripting purposes.
.IP "\fB0\fR" 4
.IX Item "0"
\&\fBapt-file\fR returned successfully.  If the command was a search, there
was at least one result.
.IP "\fB1\fR" 4
.IX Item "1"
\&\fBapt-file\fR completed a search successfully, but it had no results.
.IP "\fB2\fR" 4
.IX Item "2"
An error occurred (including invalid/conflicting user options).
.IP "\fB3\fR" 4
.IX Item "3"
\&\fBapt-file\fR could not complete the command because the cache was
empty.  Please ensure there are indices enabled in the \s-1APT\s0 config and
run \fBapt update\fR to fetch them.
.IP "\fB4\fR" 4
.IX Item "4"
\&\fBapt-file\fR could not complete the command because the cache does not
have any files matching the restrictions.  Either change the
restrictions (e.g. \fB\-\-index\-names\fR) or configure apt to fetch the
relevant files and run \fBapt update\fR.
.IP "\fB255\fR" 4
.IX Item "255"
There was an internal errors / uncaught exception in \fBapt-file\fR.
Please file a bug against \fBapt-file\fR.
.PP
Any other exit code is reserved for future use.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIapt\fR\|(1), \fIapt\-cache\fR\|(8), \fIapt.conf\fR\|(5)
.PP
The \s-1APT\s0 users guide in /usr/share/doc/apt/
.PP
The example config in /usr/share/doc/apt\-file/examples
.PP
The \s-1README\s0 at \fI/usr/share/doc/apt\-file/README.md.gz\fR