APT-FILE(1) | User Contributed Perl Documentation | APT-FILE(1) |
apt-file -- APT package searching utility -- command-line interface
apt-file [options] search pattern
apt-file [options] show package
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:
By default, the list action interprets its pattern as if --fixed-string was specified.
For a machine-readable formats (e.g. automation), please use apt-config dump (search for options starting with Acquire::IndexTargets) and apt-get indextargets for checking the cache (Look for entries with an Identifier field starting with Contents-).
Note that individual sources.list entries can override the global default. Please consult sources.list(5) for more information on advanced configuration of the sources.list files.
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-match was specified.
The only advantage using this over a regular apt update or apt-get update directly is for the case where you have configured an apt-file specific configuration (via the Dir::Etc::apt-file-main configuration option). In that case, said configuration will be included automatically.
The following options are available:
It can be a comma-separated list for searching on multiple architectures.
The configuration file will be read relative to when it appears on the command line and can overwrite options that appear before it.
Note that the config file will also be passed to all APT tools called by apt-file.
This filter matches against the name listed in the Origin field from the Release file.
If set to '*', this filter will be disabled (mostly useful for overriding the setting in a configuration file)
Alias of the APT config option: apt-file::Search-Filter::Origin
This filter matches against the name listed in the Codename and Suite fields from the Release file. This means that either "unstable" or "sid" will match Debian's unstable suite.
If set to '*', this filter will be disabled (mostly useful for overriding the setting in a configuration file)
Alias of the APT config option: apt-file::Search-Filter::Suite
This is default for show and list actions.
The name(s) must match one or more of the identifiers 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 { ... }; Acquire::IndexTargets::deb::Contents-deb-legacy { # Explicitly named to "Contents-deb" Identifier "Contents-deb"; ...; };
Then, apt-file will recognise "deb", "dsc" and "udeb" as index names.
This option defaults to the value of the "apt-file::Index-Names" apt config option (or "deb" if omitted).
Disable deduplication logic and immediately emit a result when a match is found.
This can greatly reduce the memory requirements for apt-file when processing searches with many matches. It will also reduce the time until the first match is emitted, which can be useful if matches can be processed as they are discovered and the consumer can handle duplicated matches.
This option can be used to overwrite other command line options (e.g. "-o apt-file::Search-Filter::Origin=Debian" is effectively the same as "--filter-origins Debian").
Note that the config options passed via this option will also be passed to all APT tools called by apt-file.
This is default for search and find actions.
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.
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:
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 before this file (and can override options set in it).
The file will also be passed on to all APT tools called by apt-file.
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".
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.
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.
There are some known issues or "quirks" that are good to keep in mind.
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 "/(?:usr/bin/vim|sbin/lvm)" instead of "/usr/bin/vim|/sbin/lvm".
If you search such files, you will want to set apt-file::Parser::Check-For-Description-Header to true (e.g. in /etc/apt/apt.conf.d/50apt-file.conf) to have apt-file properly filter out the headers to avoid false matches.
The reason this is not the default is that it costs a factor 2 in overhead while most common Contents files no longer have the header. (see #881405 for more details).
The default configuration by apt-file marks Contents files as optional and will just silently fail to search in Contents files in such repositories.
apt-file has the following defined exit codes, which can be used for scripting purposes.
Any other exit code is reserved for future use.
apt(1), apt-cache(8), apt.conf(5)
The APT users guide in /usr/share/doc/apt/
The example config in /usr/share/doc/apt-file/examples
The README at /usr/share/doc/apt-file/README.md.gz
2022-09-10 | perl v5.34.0 |