File: README.md

package info (click to toggle)
apt-file 3.3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, forky, sid, trixie
  • size: 636 kB
  • sloc: perl: 907; sh: 93; makefile: 40
file content (225 lines) | stat: -rw-r--r-- 8,841 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
# DESCRIPTION

apt-file helps you to find in which package a file is included. This
application has the same behaviour as the web version found at
https://packages.debian.org.

Additionally you can list all files included in a package without
installing or downloading it (see dpkg -S and dpkg --contents for more
details about listing a package content).

# GETTING STARTED

With apt-file, you can find files in packages or which packages
contains a given file.  To do this, apt-file needs access to the
Contents files, which are usually available from your mirror.  This
is done with:

    apt update

The apt command downloads the Contents files listed in its
configuration.  Here, apt-file installs
/etc/apt/apt.conf.d/50apt-file.conf to have apt download indices of
binary packages (.deb files).  Once downloaded, you can now search in
these indices by using:

    apt-file search bin/lintian
    # (or: apt-file find bin/lintian)

Alternatively, you can list all the files in a given package by using:

    apt-file show lintian
    # (or: apt-file list lintian)

NOTE: In apt-file 3, show and list takes an exact package name!  In
earlier versions of apt-file, any substring would do and it could
return multiple results.  If you want to use a substring search in
apt-file 3, please use the "--substring-match" option.

By default, apt-file will analyse the "deb" indices.  You can have it
look at other indices by using the "--index-names" option.

    apt-file --index-names dsc search frontend/lintian

    apt-file --index-names deb,udeb search bin/parted

    apt-file --index-names deb,udeb --substring-match show parted

This of course requires that you have the relevant indices available.
The indices listed in the examples above are all present in the
default /etc/apt/apt.conf.d/50apt-file.conf, although some of them are
disabled.

## Upgrading from apt-file 2

The upgrade from apt-file 2 to apt-file comes with a number of
important changes.

### Backwards incompatible changes

 * The format of /etc/apt/apt-file.conf is now an APT
   configuration file.
 * The following command line options have been removed:
    * --cache
    * --cdrom-mount / -d
    * --dummy / -y
    * --non-interactive / -N
 * Command line options/commands have changed behaviour/meaning
    - The "-c" option is now "--config" (reads an APT config file)
    - The "show"/"list" command now does an "exact match" (-F)
      by default.  Use "--substring-match" to get the previous
      behaviour.
    - The "-a" option cannot be used with "source" or "udeb-$ARCH".
      Please use the new "--index-names" option.  Remember to
      configure APT to download the extra Contents files.
 * User caches are no longer supported by default.
   - This can be emulated via a user config file to change
     the APT cache location.
 * The "diffindex-download" and "diffindex-rred" tools
   have been removed.
 * apt-file has changed its exit codes.
   - Notably, it returns "non-zero" when there are no
     matches to the queries.
   - Please review the manpage for the different exit
     codes.
 * apt-file now uses "gnu-getopt" option style parsing.
   - If you have been relying on the undocumented feature
     of using "+" instead of "-" when specifying options,
     it will no longer work.

### Improvements due to using APT's acquire system

 * Contents files are now updated when using "apt update".
   - If download sizes or/and speed are a concern, please
     review the "OPTIMISING CONTENTS DOWNLOADS" section
     below.
 * apt-file now supports the Contents files being compressed
   in *any* compression format supported by APT.
 * apt-file now supports any sources.list file and download
   protocol that apt supports.  This includes:
   - The deb822 sources files
   - Protocols like "mirror" or "tor+http(s)"
   - Respecting APT's proxy settings

# OPTIMISING CONTENTS DOWNLOADS

There are a couple of methods to optimise the time / bandwidth used
by fetching new Contents files.

 * Ensure that PDiffs are enabled for Contents files
   - This is the default for apt-file/3, but your local configuration
     might have disabled it.
   - Keep in mind that PDiff cannot be used for the initial download
     or if it has been too long since your last update.
   - NB: Not all suites/distributions provide these.  Notably Ubuntu's
     development suites do ''not'' offer PDiffs.
 * Use apt/1.2 and its LZ4 compression for Contents files (requires
   PDiffs)
   - When fetching PDiffs, apt will recompress the Contents files as
     LZ4, which is vastly faster to decompress/compress than gzip.
   - This also gives a much faster search speed with apt-file.
 * Disable fetching of Contents files you do not need/want.
   - See the "Choosing which Contents files to fetch" section below.

If you are tracking a rapidly updating distribution, which does
''not'' have PDiffs, you probably want to disable fetching Contents by
default for that distribution.

## Choosing which Contents files to fetch

Even if you track multiple suites (or mirrors), you may not want to
download Contents files for all of them.

Here are a couple of suggestions:

 * If you track unstable + testing, you can probably omit the Contents
   files for testing without any issues.
 * Contents-dsc (source) has a rather large churn and even its PDiffs
   are large.
   - It is not enabled by default, but consider if you really need it
     before enabling it.

## Configuring APT to fetch fewer Contents files

There are several ways to do this:

 * Disable all Contents files by default and then enable them on a
   per source.list entry basis.
   - The example config file 60disable-contents-fetching.conf may be
     a useful starting point.  The full path is
     /usr/share/doc/apt-file/examples/60disable-contents-fetching.conf

 * Disable Contents files for a given source.list entry

To disable/enable Contents fetching globally, simply set:

    Acquire::IndexTargets::deb::Contents-deb::DefaultEnabled

in your APT config to the desired value.  This works similarly with
other indices (remember to replace "::deb::" with "::deb-src::" for
the "Contents-dsc" target).

Then in your sources.list, you can manually enable/disable them on a
per target basis:

    deb [target+=Contents-deb] $MIRROR/debian unstable main ...
    deb [target-=Contents-deb] $MIRROR/debian unstable main ...

Note that the "Contents-dsc" should be on a "deb-src" entry.

For more information on this, please refer to "man 5 sources.list"
and "man 5 apt.conf"


## Download sizes

If you are interested in the download sizes involved, here are a few
numbers from Debian amd64 unstable (only the main component).

 * Full Contents: ~30MB (per download)
   - Measured in Feb 2016.
 * PDiffs: ~1.15MB/day
   - Average of PDiffs over 14 days in Feb 2016.

Accordingly, if you update your Contents files more frequently than
every once every ~26 days, it is (on average) cheaper to use PDiffs.
Of course, if you use a different distribution, your mileage may
vary.

**NOTE**: The "apt update" after installing apt-file 3 (or upgrading
from apt-file 2) *cannot* use PDiffs.  This is because PDiffs
are basically patches to your existing Contents files.


## PDiffs and speed

The original PDiff support in APT unfortunately suffered from a
number of performance issues.  This has lead to the general opinion
that "PDiffs are slow".

However, APT has implemented a number of improvements to the PDiff
performance (note that "rred" is the program applying the PDiffs).

 * Client-side PDiff merging since APT 0.9.14.3~exp2 (2014-01)
   - This greatly reduces the time taken to apply multiple PDiffs
   - Note that apt-file 2 had this feature for a long time.
 * Buffered reads in "rred" since APT 1.1.6 and 1.1.7 (2015-12)
 * Parallel running of "rred" since APT 1.2~exp1 (2016-01)
   - This makes APT apply PDiffs on Packages and Contents files in
     parallel (provided you got multiple CPU cores).
 * Recompression of Contents files to lz4 since APT 1.2~exp1 (2016-01)
   - This removes a major overhead in reading and writing gzipped
     Contents files.
   - This comes at a cost of compression ratio (~x2).
   - Alternatively, if disk space is important, you can use a
     better compressor (e.g. xz) at the cost of more time
     spent compressing.

If you are interested in the details of these improvements in APT,
please have a look at the following blog posts of Julian Andres Klode:

 * [Much faster incremental apt updates][much-faster-incremental-apt-updates]
 * [APT 1.1.8 to 1.1.10 – going “faster”][apt-1-1-8-to-1-1-10-going-faster]

[much-faster-incremental-apt-updates]: https://blog.jak-linux.org/2015/12/26/much-faster-incremental-apt-updates/
[apt-1-1-8-to-1-1-10-going-faster]: https://blog.jak-linux.org/2015/12/30/apt-1-1-8-to-1-1-10-going-faster/