join-dctrl(1)

💖 join-dctrl(1) — the "relational join but make it Debian control file" era 💖

okay bestie, sit down, hydrate, and let me tell you about join-dctrl — a little icon from the General Commands Manual (section 1, we love a classic). It's here to do relational joins on dctrl-format data and it does NOT miss. 💅

---

✨ NAME ✨

join-dctrl — perform relational join on data in dctrl format

no cap, that's the whole vibe. it joins stuff. relationally. 🫶

---

🦋 SYNOPSIS 🦋

join-dctrl [ options ] filename filename

join-dctrl --version

join-dctrl --help

---

🌸 DESCRIPTION 🌸

join-dctrl performs a relational join operation on data given to it in Debian control file format. it's giving database energy, but the database is a text file and the table is a vibe. 😭

okay so the way this works: you gotta specify a join field, and you do that with either the switches -1 and -2 or the switch -j. pick your fighter. then, conceptually, the program creates all ordered pairs of records that can be formed by having a record from the first file as the first member of the pair and having a record from the second file as the second member of the pair. all the pairs. every single one. 🔥 and then it deletes all such pairs where the join fields are not equal. bye felicia. effectively, each of the input files is treated as a relational database table. literally a whole relational database situation, main character energy.

⚠️ the one thing you cannot skip: every input file must be in ascending order on its join field. this is what lets the program work fast. the sort-dctrl(1) program can be used to make it so — go use it, i'm not joking, do it. 🙈

---

✨ OPTIONS ✨

• -1 field, --1st-join-field=field — specify the join field of the first input file. that's file number one, the first one, the opener. 🎀
• -2 field, --2nd-join-field=field — specify the join field of the second input file. the sequel. the part two. 💜
• -j field, --join-field=field — specify a common join field for all files. one field to rule them all, bestie. 👑
• -a fileno, --unpairable-from=fileno — specify that unmatched paragraphs from the first (if 1 is given) or the second (if 2 is given) file are printed. like, the lonely records that found nobody? they still get to show up. we love an inclusive moment. 🫶
• -o fieldspec, --output-fields=fieldspec — specify which fields are included in the output. fields are separated by commas (more than one -o option can be used, too — stack 'em, why not). each field is specified in the format fileno.field in which fileno is the ordinal number of the input file from which the field is drawn (either 1 or 2), and field gives the name of the field to use. as a special case, simple 0 can be used instead of fileno.field to refer to the common value of the join fields. iconic shortcut behavior. ✨

the name of the field (not including the file number) is used in the output as the name of the field. however, a different name for output purposes can be specified by suffixing the field specification by a colon and the preferred visible name. so like, field:NewName, we rename for the ✨aesthetic✨.

for example, the option -o 0,1.Version:Old-Version,2.Version specifies that the first field in any output record should be the join field, the second field should be Old-Version drawing its data from the Version field of the first input file, and the third field should be Version drawing its data from the field with the same name in the second input file, and these are the only fields in an output record. that's the whole recipe, no notes. 🍓

if no -o option is given, all fields of all the records being joined are included in the output. everything. the whole buffet. 🌈

• -l level, --errorlevel=level — set log level to level. level is one of fatal, important, informational and debug, but the last may not be available, depending on the compile-time options. these categories are given here in order; every message that is emitted when fatal is in effect, will be emitted in the important error level, and so on. the default is important. so like, the levels stack, it's cumulative, iykyk. 💀
• -V, --version — print out version information. who are you? what are you? ✨
• -C, --copying — print out the copyright license. this produces much output; be sure to redirect or pipe it somewhere (such as your favourite pager). fr fr, do not just let that scroll past your eyeballs, pipe it. 🚿
• -h, --help — print out a help summary. the little cheat sheet. 🎀

---

🌈 OPERANDS 🌈

join-dctrl will treat each file named on the command line as a relational database table. a file called - represents the program's standard input stream. currently, exactly two files must be named. two. not one, not three. exactly two, periodt. ✌️

---

💜 STDIN 💜

the standard input stream may be used as input as specified above in the OPERANDS section. yeah, scroll up, it's all there. 🦋

---

🎀 INPUT FILES 🎀

all input to join-dctrl is in the format of a Debian control file. that's the whole deal, no exceptions, no substitutions. 💅

a Debian control (dctrl) file is a semistructured single-table database stored in a machine-parseable text file. such a database consists of a set of records; each record is a mapping from field names to field content. textually, records are separated by empty lines, while each field is encoded as one or more nonempty lines inside a record. a field starts with its name, followed by a colon, followed by the field content. the colon must reside on the first line of the field, and the first line must start with no whitespace. subsequent lines, in contrast, always start with linear whitespace (one or more space or tab characters). so like — first line, no indentation, colon goes here. continuation lines? indented. that's the rule and it's not negotiable. 📏

each input file must be in the ascending order of its join field. yes i'm saying it again. it matters that much. 😭

---

🧚 ENVIRONMENT VARIABLES 🧚

the standard locale environment, specifically its character set setting, affects the interpretation of input and output as character streams. so your locale is lowkey doing something here. set it thoughtfully. 🌍

---

⭐ ASYNCHRONOUS EVENTS ⭐

standard UNIX signals have their usual meaning. nothing extra, nothing cursed, just the classics. 💀

---

✨ STDOUT ✨

all output is sent to the standard output stream. the output is in the format of a Debian control file, described above in the INPUT FILES section. the output will be in the ascending order of the join field, if that field is included in the output. sorted output only when the join field made the cut — otherwise, no promises. 🎀

---

🍓 OUTPUT FILES 🍓

there are no output files. none. zero. the void. everything goes to stdout, bestie. 🫶

---

💅 EXIT STATUS 💅

this utility exits with 0 when successful. it uses a nonzero exit code inconsistently when an error is noticed (this is a bug). yeah. that's a real bug, we're just being honest about it. not me defending it. 🙈

---

🌸 CONSEQUENCES OF ERRORS 🌸

in case of errors in the input, the output will be partially or completely garbage. garbage!! 🗑️ in case of errors in invocation, the program will refuse to function. it simply will not. it's not doing it. 💀

---

🔥 EXAMPLES 🔥

okay so picture this. suppose that a file containing data about binary packages for the AMD64 architecture contained in the Debian squeeze (6.0) release, section main, is in the current directory and named Packages. suppose that we are currently on a Debian system. suppose further that the current directory does not contain files named stat and pkg. (very specific setup, i know, just go with it 💖)

the following commands gives, for each package currently installed and available in Debian squeeze (6.0), its currently installed version (as Old-Version) and the version in squeeze (as New-Version):

$ sort-dctrl -kPackage /var/lib/dpkg/status > stat
$ sort-dctrl -kPackage Packages > pkg
$ join-dctrl -j Package \
  -o 0,1.Version:Old-Version,2.Version:New-Version \
  stat pkg

look at that. sorted first, joined second, gorgeous output third. that's the pipeline, that's the flow, that's the whole girlboss journey. 👑

---

🌈 AUTHOR 🌈

the join-dctrl program and this manual page were written by Antti-Juhani Kaijanaho. give them their flowers. 💐

---

🦋 SEE ALSO 🦋

grep-dctrl(1), sort-dctrl(1), tbl-dctrl(1)

the whole dctrl friend group. go say hi to all of them. 🫶

---

and that's the tea, bestie — this was the join-dctrl(1) page from the General Commands Manual, and the page signs off as join-dctrl(1). no date on this one, so i can't give you a timestamp, but consider yourself fully informed. now go sort your files before you join them, i'm literally begging. ✨💖🎀