GREP-DCTRL(1)

📦 version 2.24, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

omg bestie, welcome to GREP-DCTRL(1) — the Debian user's manual page for the whole grep-dctrl squad. It's giving "grep, but make it Debian control files," and honestly? We're obsessed. 💖

✨ NAME ✨

  • grep-dctrl, grep-status, grep-available, grep-aptavail, grep-debtags — these are the besties that grep Debian control files. Periodt. 💅

🌸 SYNOPSIS 🌸

command --copying|-C | --help|-h | --version|-V

command [options] filter [ file... ]

where command is one of grep-dctrl, grep-status, grep-available, grep-aptavail and grep-debtags.

💅 DESCRIPTION 💅

okay so grep-dctrl is literally the program you call when you need answers like: "What is the Debian package foo?", "Which version of the Debian package bar is now current?", "Which Debian packages does John Doe maintain?", "Which Debian packages are somehow related to the Scheme programming language?", and, with some help, "Who maintain the essential packages of a Debian system?" — all given a useful input file. 👑

The programs grep-available, grep-status, grep-aptavail and grep-debtags are aliases of (actually, symbolic links to) grep-dctrl. These aliases use as their default input the dpkg(1) available and status files, the apt-cache dumpavail output and the debtags dumpavail output, respectively. 🫶

grep-dctrl is a specialised grep program that is meant for processing any file which has the general format of a Debian package control file, as described in the Debian Policy. These include the dpkg available file, the dpkg status file, and the Packages files on a distribution medium (such as a Debian CD-ROM or an FTP site carrying Debian). No cap. ✨

You must give a filter expression on the command line. The filter defines which kind of paragraphs (aka package records) are output. A simple filter is a search pattern along with any options that modify it. Possible modifiers are --eregex, --field, --ignore-case, --regex and --exact-match, along with their single-letter equivalents. By default, the search is a case-sensitive fixed substring match on each paragraph (in other words, package record) in the input. With suitable modifiers, this can be changed: the search can be case-insensitive and the pattern can be seen as an extended POSIX regular expression. 💖

Filters can be combined to form more complex filters using the connectives --and, --or and --not. Parentheses (which usually need to be escaped for the shell) can be used for grouping. 🌸

By default, the full matching paragraphs are printed on the standard output; specific fields can be selected for output with the -s option. 👑

After the filter expression comes zero or more file names. The file name - is taken to mean the standard input stream. The files are searched in order but separately; they are not concatenated together. In other words, the end of a file always implies the end of the current paragraph. 💀

If no file names are specified, the program name is used to identify a default input file. The program names are matched with the base form of the name of the current program (the 0'th command line argument, if you will). 🙈

✨ OPTIONS ✨

okay bestie, this is the part where the real power lives 💅 every single flag, no skips, let's go

🌸 Specifying the search pattern

  • --pattern=pattern — tell grep-dctrl what pattern to hunt for. ngl you'll barely ever need this one, because you can just hand the pattern over on its own like a normal person. BUT 🚨 if your pattern starts with a dash (-), you have to use this switch, otherwise it gets mistaken for a switch and everything gets weird. periodt.

🎀 Modifiers of simple filters

these are the lil' seasonings you sprinkle on a simple filter to change how it matches 👑

  • -F field,field, ... | --field=field,field, ... — keep the pattern matching locked to only the fields you name. you can stack multiple field names inside one -F option and stack multiple -F options in one simple filter, and that's totally fine 💖 the search happens across all the fields you named, and the moment any one of them matches, the whole simple filter counts as matching. slay.
a field spec can contain a colon (:). when it does, everything before the colon is the name of the field you're searching in, and everything after the colon is the name of the field whose content gets used if the field you're searching in turns out empty. 🫶
  • -P — cute shorthand for -FPackage. ✨
  • -S — cute shorthand for -FSource:Package. ✨
  • -e, --eregex — treat the pattern of the current simple filter as an extended POSIX regular expression. regex girlies rise 🌈
  • -r, --regex — treat the pattern of the current simple filter as a standard POSIX regular expression.
  • -i, --ignore-case — ignore case when matching in the current simple filter. casing? never heard of her 💅
  • -X, --exact-match — do an exact match, as opposed to a substring match, in the current simple filter. no half-matches, we're precise here 👑
  • -w, --whole-pkg — do an extended regular expression match on whole package names, assuming the syntax of inter-package relationship fields such as Depends,Recommends, ... when this flag is on, you don't have to stress about sub-package names like "libpcre3" also matching "libpcre3-dev" 😭 this flag implies (and is incompatible with) -e.
  • --eq — do an equality comparison under the Debian version number system. if the pattern, or the field being searched in, isn't a valid Debian version number, the paragraph is treated as not matching. as a special case, this can compare simple nonnegative integers for equality. 🧮
  • --lt — do a strictly-less-than comparison under the Debian version number system. if the pattern, or the field being searched in, isn't a valid Debian version number, the paragraph is treated as not matching. as a special case, this can compare simple nonnegative integers. 🧮
  • --le — do a less-than-or-equal comparison under the Debian version number system. if the pattern, or the field being searched in, isn't a valid Debian version number, the paragraph is treated as not matching. as a special case, this can compare simple nonnegative integers. 🧮
  • --gt — do a strictly-greater-than comparison under the Debian version number system. if the pattern, or the field being searched in, isn't a valid Debian version number, the paragraph is treated as not matching. as a special case, this can compare simple nonnegative integers. 🧮
  • --ge — do a greater-than-or-equal comparison under the Debian version number system. if the pattern, or the field being searched in, isn't a valid Debian version number, the paragraph is treated as not matching. as a special case, this can compare simple nonnegative integers. 🧮

🦋 Combining filters

this is where you build the actual logic tree, and honestly? main character energy 🌟

  • -!, --not, ! — match if the following filter does not match. 😈
  • -o, --or — match if either one or both of the preceding and following filters matches. yes queen, inclusivity 🫶
  • -a, --and — match if both the preceding and the following filter match. both. not one. both. 💯
  • ( ... ) — parentheses for grouping, bestie 🎀 heads up though: you'll need to escape them for most shells. filter modifiers can be placed before the opening parenthesis, and they get treated as if they'd been repeated for every single simple filter inside the parentheses. so you can be lazy and efficient at the same time, iconic.

🌈 Output format modifiers

  • -l, --files-with-matches — output only the file names, each on its own line, of the files that contain at least one matching paragraph. this is incompatible with -v and -L, and literally every other output format modifier just gets ignored. 🙈
  • -L, --files-without-matches — output only the file names, each on its own line, of the files that contain no matching paragraphs. this is incompatible with -v and -l, and again all other output format modifiers get ignored. 🙈
  • -s field,field, ... | --show-field=field,field, ... — show only the body of these fields from the matching paragraphs. the field names must not include any colons or commas (commas are what delimits field names in this option's argument, so yeah). the fields get shown in the order you gave them here. also see -I 👀 and note that without the --ensure--dctrl option, if only one field is selected, no paragraph separator is output.
  • -I, --invert-show — flip the meaning of -s: show only the fields that were not named using a -s option. as an artefact of the implementation, the order of the fields in the original paragraph is not preserved. 🌀

A field specification can contain a colon. In such a case, the part up to the colon is taken as the name of the field to be shown, and the part after the colon is taken as the name of the field whose content is to be used if the field to be shown is empty.

  • -d — show only the first line of the Description field from the matching paragraphs. if no -s option is specified, this option also effects -s Description; if there is a -s option but it doesn't include the Description field name, one gets appended to the option. so the Description field's location in the output is decided by the -s option, if any, with the last field being the default. 💅
  • -n, --no-field-names — suppress field names when showing specified fields, so only their bodies show up. each field is printed in its original form, without the field name, the colon after it, and any whitespace before the start of the body. ✨
  • -v, --invert-match — instead of showing all the paragraphs that match, show the ones that don't match. 🔄
  • -c, --count — instead of showing the matching paragraphs (or, with -v, the non-matching ones), show the count of those paragraphs. 🔢
  • -q, --quiet, --silent — output nothing to the standard output stream. instead, exit immediately after finding the first match. gone. vanished. silent like a ninja 🥷

🧚 Miscellaneous

  • --ensure-dctrl — make sure the output is in dctrl format, specifically that there's always an empty line separating paragraphs. this option is not honored if -n has been selected, because that option deliberately requests a non-dctrl output format. heads up: in a future version, this option may be made the default behaviour. ⚠️
  • --compat — override any --ensure-dctrl option given earlier on the command line. 🫡
  • --ignore-parse-errors — ignore errors while parsing input. a paragraph that can't be parsed is ignored in its entirety, and the next paragraph is assumed to start after the first newline since the location of the error. 🙈
  • --debug-optparse — show how the current command line has been parsed. peek behind the curtain, bestie 🔍
  • --errorlevel=level — set the log level to level. level is one of fatal, important, informational and debug — though that last one may not be available, depending on the compile-time options 👀 these categories are given here in order; every message emitted when fatal is in effect will also be emitted at the important error level, and so on. the default is important.
  • -V, --version — print out version information. 💖
  • -C, --copying — print out the copyright license. this produces a lot of output, so be sure to redirect or pipe it somewhere, like your favourite pager. no cap, it's long 📜
  • -h, --help — print out a help summary. 🫶

✨ EXAMPLES ✨

okay bestie, this is the fun part 🎀 — let's actually do stuff with this thing.

The almost simplest use of this program is to print out the status or available record of a package. In this respect, grep-dctrl is like dpkg -s or dpkg --print-avail. To print out the status record of the package "mixal", do

% grep-status -PX mixal

and to get its available record, use

% grep-available -PX mixal

In fact, you can ask for the record of the "mixal" package from any Debian control file. Say you have the Debian 6.0 CD-ROM's Packages file in the current directory; now you can do a

% grep-dctrl -PX mixal Packages

But grep-dctrl can do more than just emulate dpkg. It can more-or-less emulate apt-cache too! 👑 That program has a search feature that searches package descriptions. But we can do that too:

% grep-available -F Description foo

searches for the string "foo" case-sensitively in the descriptions of all available packages. If you want case-insensitivity, use

% grep-available -F Description -i foo

Truth to be told, apt-cache searches package names too. We can separately search in the names; to do so, do

% grep-available -F Package foo

or

% grep-available -P foo

which is pretty much the same thing. We can also search in both descriptions and names; if a match is found in either, the package record is printed:

% grep-available -P -F Description foo

or

% grep-available -F Package -F Description foo

This kind of search is the exactly same that apt-cache does. 💅

Here's one thing neither dpkg nor apt-cache do. Search for a string in the whole status or available file (or any Debian control file, for that matter) and print out all package records where we have a match. Try

% grep-available dpkg

sometime and watch how thoroughly dpkg has infiltrated Debian. 😭 iconic honestly.

All the above queries were based on simple substring searches. But grep-dctrl can handle regular expressions in the search pattern. For example, to see the status records of all packages with either "apt" or "dpkg" in their names, use

% grep-status -P -e 'apt|dpkg'

Now that we have seen all these fine and dandy queries, you might begin to wonder whether it is necessary to always see the whole paragraph. You may be, for example, interested only in the dependency information of the packages involved. Fine. To show the depends lines of all packages maintained by me, do a

% grep-available -F Maintainer -s Depends 'ajk@debian.org'

If you want to see the packages' names too, use

% grep-available -F Maintainer -s Package,Depends \
  'ajk@debian.org'
Note that there must be no spaces in the argument to the -s switch. 🫶

More complex queries are also possible. For example, to see the list of packages maintained by me and depending on libc6, do

% grep-available -F Maintainer 'ajk@debian.org' \
   -a -F Depends libc6 -s Package,Depends

Remember that you can use other UNIX filters to help you too. Ever wondered who's the most active Debian developer based on the number of source packages being maintained? Easy. You just need to have a copy of the most recent Sources file from any Debian mirror.

% grep-dctrl -n -s Maintainer '' Sources | sort | \
  uniq -c | sort -nr

This example shows a neat trick: if you want to selectively show only some field of all packages, just supply an empty pattern. 🌸

The term "bogopackage" means the count of the packages that a Debian developer maintains. To get the bogopackage count for the maintainer of dctrl-tools, say

% grep-available -c -FMaintainer \
  "`grep-available -sMaintainer -n -PX dctrl-tools`"

Sometimes it is useful to output the data of several fields on the same line. For example, the following command outputs the list of installed packages, sorted by their Installed-Size.

% grep-status -FStatus -sInstalled-Size,Package -n \
  "install ok installed" -a -FInstalled-Size --gt 0 \
  | paste -sd "  \n" | sort -n
Note that there should be exactly 2 spaces in the " \n" string. not one, not three, TWO. 💀

Another usual use-case is looking for packages that have another one as build dependency:

% grep-dctrl -s Package -F Build-Depends,Build-Depends-Indep \
  quilt /var/lib/apt/lists/*Sources

These examples cover a lot of typical uses of this utility, but not all possible uses. Use your imagination! ✨ The building blocks are there, and if something's missing, let me know.

🩺 DIAGNOSTICS 🩺

In the absence of errors, the exit code 0 is used if at least one match was found, and the exit code 1 is used if no matches were found. If there were errors, the exit code is 2, with one exception. If the -q, --quiet or --silent options are used, the exit code 0 is used when a match is found regardless of whether there have been non-fatal errors. 🙈

These messages are emitted in log levels fatal and important. Additional messages may be provided by the system libraries. This list is incomplete. (ngl, very "we tried our best" energy 💜)

  • A pattern is mandatory — You must specify a pattern to be searched for.
  • malformed filter — No filter was specified, but one is required.
  • cannot find enough memory — More memory was needed than was available. This error may be transient, that is, if you try again, all may go well.
  • cannot suppress field names when showing whole paragraphs — When you do not use the -s switch, grep-dctrl just passes the matching paragraphs through, not touching them any way. This means, for example, that you can only use -n when you use -s.
  • inconsistent modifiers of simple filters — Conflicting modifiers of simple filters were used; for example, perhaps both -X and -e were specified for the same simple filter.
  • missing ')' in command line — There were more opening than closing parentheses in the given filter.
  • no such log level — The argument to --errorlevel was invalid.
  • too many file names — The number of file names specified in the command line exceeded a compile-time limit.
  • too many output fields — The argument to -s had too many field names in it. This number is limited to 256.
  • unexpected ')' in command line — There was no opening parenthesis that would match some closing parenthesis in the command line.

📁 FILES 📁

  • /var/lib/dpkg/available — The default input file of grep-available.
  • /var/lib/dpkg/status — The default input file of grep-status.

🖊️ AUTHOR 🖊️

The program and this manual page were written by Antti-Juhani Kaijanaho <gaia@iki.fi>. Bill Allombert <ballombe@debian.org> provided one of the examples in the manual page. (shoutout to both of them fr fr 🫶)

👀 SEE ALSO 👀

Debian Policy Manual. Published as the Debian package debian-policy. Also available in the Debian website.

apt-cache(1), ara(1), dpkg-awk(1), sgrep(1), dpkg(8)

and that's the whole page bestie!! 🎀 this lil gem comes to you from the Debian Project, dated 2013-11-26, and it lives in the man pages as GREP-DCTRL(1). go grep something, you're gonna slay 💅✨

📦 where this page comes from