Metadata-Version: 2.4
Name: apt-file-fast
Version: 1.0.1
Summary: Fast sharded-index replacement for apt-file search on Debian/Ubuntu.
Project-URL: Homepage, https://github.com/izumo-m/apt-file-fast
Project-URL: Repository, https://github.com/izumo-m/apt-file-fast
Project-URL: Issues, https://github.com/izumo-m/apt-file-fast/issues
Author-email: Masanao Izumo <49137441+izumo-m@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: apt,apt-file,debian,dpkg,package-search,ripgrep,ubuntu
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: zstandard>=0.22
Description-Content-Type: text/markdown

# apt-file-fast

A fast replacement for `apt-file search` on Debian/Ubuntu — with **dramatically faster index creation**.

`apt-file-fast` builds and maintains a local search index of the files provided by your
installed packages. Updates are incremental: only the data for packages added, removed, or
changed since the last run is rewritten, so refreshing after `apt install` / `apt upgrade`
is **orders of magnitude faster than `apt-file update`**.

## Requirements

- Debian or Ubuntu
- Python 3.10+
- [`ripgrep`](https://github.com/BurntSushi/ripgrep) (`apt install ripgrep`)

## Install

### From PyPI (recommended)

```bash
uv tool install apt-file-fast
```

Or run it one-shot without installing:

```bash
uvx apt-file-fast --help
```

### From source

```bash
git clone https://github.com/izumo-m/apt-file-fast.git
cd apt-file-fast
uv sync
uv run apt-file-fast --help
```

## Usage

Build or refresh the index (run once, then after every `apt install`/`apt upgrade`):

```bash
apt-file-fast update
```

Search for a file across all installed packages:

```bash
apt-file-fast search ls
apt-file-fast search -i README            # case-insensitive
apt-file-fast search -x '^/usr/bin/py.*'  # regex
```

Search without building the index — scan `/var/lib/dpkg/info/*.list`
directly. Useful right after install (no `update` needed) or when you
want a result that always reflects current dpkg state:

```bash
apt-file-fast search --no-cache /bin/ls
```

Clear the cache:

```bash
apt-file-fast clean
```

### Options

| Option              | Scope        | Description                              |
| ------------------- | ------------ | ---------------------------------------- |
| `--cache-dir PATH`  | all commands | Override cache location                  |
| `-i, --ignore-case` | `search`     | Case-insensitive match                   |
| `-x, --regexp`      | `search`     | Treat the query as a regex               |
| `--no-cache`        | `search`     | Skip the index; grep dpkg state directly |

Index settings (compression, shard size, etc.) live in `manifest.json` and
are edited via `config set` rather than `update` flags — see below.
Run `apt-file-fast --help` for the full list of options.

### Configuration

Index settings are stored in the cache's `manifest.json`. View them or
change individual fields without rebuilding the index:

```bash
apt-file-fast config show
apt-file-fast config set --compression zstd --compression-level 7
apt-file-fast config set --search-threads 4
apt-file-fast config set --target-shard-bytes 1M
```

`config set` only persists the fields you pass; everything else is left
alone. A first-time `update` with no manifest auto-generates one with
the built-in defaults, so `config set` is optional.

#### Compression

Shards are zstd-compressed by default — both compression and decompression
are several times faster than gzip at comparable ratios for this kind of
repetitive TSV data. Each shard's filename (`shard-NNNN.tsv.zst` / `.tsv.gz`
/ `.tsv`) reflects how it is encoded, so a single cache directory can
legitimately hold a mix of formats during a migration — `search`
transparently handles all three via `rg -z`.

#### Migrating after a config change

Changing `compression`, `compression_level`, or `target_shard_bytes` only
affects shards written *after* the change. Existing shards are carried
verbatim by `update` until the packages they hold are added, removed, or
changed. To force every shard onto the new setting:

```bash
apt-file-fast config set --compression zstd
apt-file-fast clean && apt-file-fast update
```

`config set` prints a reminder to stderr when it detects that a
cache-affecting field changed against an existing index.

## License

[MIT](LICENSE) © 2026 Masanao Izumo

---

Contributors and maintainers: see
[`docs/development.md`](https://github.com/izumo-m/apt-file-fast/blob/main/docs/development.md)
for internals and the release process.
