join-dctrl

join-dctrl [-u] [-m] field1 [field2 ...] [--] [file1 file2 ...]

-u
    Output only unique records based on the primary key identified from the input data. If multiple records share the same primary key, only the first encountered will be output.

-m
    Output only the fields explicitly specified as arguments (field1, field2, etc.) and the primary key fields. By default, without this option, it might include more fields from the matched records.

field1 [field2 ...]
    One or more field names to be included in the output. These fields will be extracted from the joined records. The order specified here will be preserved in the output.

file1 [file2 ...]
    Paths to input files in Debian control file format. If no files are specified, join-dctrl reads from standard input (stdin).

--
    Marks the end of options and the beginning of positional arguments (file names), useful if a file name might start with a hyphen.

join-dctrl is a specialized utility designed to merge and process records from Debian control files (dctrl format). It operates similar to the standard join(1) command but is tailored to handle the specific multi-field paragraph structure found in Debian package control files, changelogs, or other dctrl-formatted data.

Typically, it reads records from two or more input files (or standard input), identifies common records based on implicit primary keys (like 'Package' and 'Version' or 'Source' and 'Version'), and outputs merged records with selected fields. It's not commonly invoked directly by users but serves as an internal component for other dpkg-dev tools, such as dpkg-mergechangelogs(1), to combine and rationalize control information.

This command is primarily an internal utility of the dpkg-dev package and lacks a standard man page on most systems. Its direct use by end-users is uncommon.
It expects input data to be in the Debian control file format, where records are separated by empty lines and fields within a record are 'Field-Name: Value'.
The primary key used for joining (e.g., 'Package'/'Version' or 'Source'/'Version') is implicitly determined by the script based on the available fields, which might not always be what a user intends for complex joining scenarios.

join-dctrl expects input to conform to the Debian control file format. This means data consists of paragraphs (records) separated by one or more blank lines. Each line within a paragraph represents a field in the format 'Field-Name: Value'.

The output is also in Debian control file format, with merged records. Each output record will contain the primary key fields and the fields explicitly requested by the user. If the -m option is not used, it might include additional fields from the matched records.

join-dctrl is part of the dpkg-dev package, which provides tools for unpacking, building, and managing Debian packages. It has been an integral, though internal, component since at least the early 2000s, primarily serving the purpose of intelligently merging control information from various sources during package building and management processes. Its design reflects the specific needs of Debian's package metadata format.

dpkg-mergechangelogs(1), dpkg(1), join(1), cat(1)