JOIN(1)

📦
version 9.10 · 5 versions
, in ubuntu stonking

🌸 JOIN(1) — the manual page, but make it cute 🌸

okay bestie, settle in, because join from the User Commands section is genuinely one of the most underrated little tools in the whole toolbox and i need you to be obsessed with it 💖

✨ NAME ✨

join — join lines of two files on a common field. that's it. that's the whole vibe. two files, one shared field, they get married. 💍

✨ SYNOPSIS ✨

join [OPTION]... FILE1 FILE2

✨ DESCRIPTION ✨

so here's the tea 🍓: for every pair of input lines that have identical join fields, it writes a line to standard output. that's the whole friendship. the default join field is the first one, delimited by blanks.

and listen — when FILE1 or FILE2 is - (not both, bestie, one or the other, don't get greedy 🙈), that file is read from standard input.

the options, one by one, no skipping 💅

  • -a FILENUM — also print unpairable lines from file FILENUM, where FILENUM is 1 or 2, corresponding to FILE1 or FILE2. like, don't ghost the lonely lines, okay?
  • -e STRING — replace missing (empty) input fields with STRING. I.e., the missing fields you specified with the -12jo options get filled in with your STRING instead of just... nothing.
  • -i, --ignore-case — ignore differences in case when comparing fields. uppercase, lowercase, it's all love here 💖
  • -j FIELD — equivalent to -1 FIELD -2 FIELD. one flag, both files, so efficient, so iconic.
  • -o FORMAT — obey FORMAT while constructing the output line.
  • -t CHAR — use CHAR as the input and output field separator. changes everything about how fields are read, no cap.
  • -v FILENUM — like -a FILENUM, but suppress joined output lines. so you only see the unpaired ones. the solo era. periodt.
  • -1 FIELD — join on this FIELD of file 1.
  • -2 FIELD — join on this FIELD of file 2.
  • --check-order — check that the input is correctly sorted, even if all input lines are pairable. it does not care that things happen to work out, it WILL check. 👑
  • --nocheck-order — do not check that the input is correctly sorted. live your truth. (risky. but your call.)
  • --header — treat the first line in each file as field headers, print them without trying to pair them. little VIP line, exempt from the whole matching situation.
  • -z, --zero-terminated — line delimiter is NUL, not newline. for when newlines are simply not the moment.
  • --help — display this help and exit. the classic.
  • --version — output version information and exit.

the rules of the format game ✨

unless -t CHAR is given, leading blanks separate fields and are ignored. if -t CHAR is given, then fields are separated by CHAR, full stop.

any FIELD is a field number counted from 1.

FORMAT is one or more comma or blank separated specifications, each one being FILENUM.FIELD or 0.

the default FORMAT outputs the join field, the remaining fields from FILE1, the remaining fields from FILE2, all separated by CHAR.

and if FORMAT is the keyword auto, then the first line of each file determines the number of fields output for each line. brainy behavior honestly 🧚

IMPORTANT, like actually important: FILE1 and FILE2 must be sorted on the join fields.

e.g., use sort -k 1b,1 if join has no options, or use join -t '' if sort has no options. 😭

Comparisons honor the rules specified by LC_COLLATE.

and if the input is not sorted and some lines cannot be joined, a warning message will be given. so like... you'll know. you'll know.

✨ AUTHOR ✨

Written by Mike Haertel. king behavior, we love him for it 👑

✨ REPORTING BUGS ✨

found a bug? spill it 💌

✨ SEE ALSO ✨

Packaged by Ubuntu (9.10-1ubuntu2).

Copyright © 2026 Free Software Foundation, Inc.

License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html.

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law.

and that's the whole page, bestie 🫶 this was GNU coreutils 9.10, from August 2026, and you just read JOIN(1). go sort your files, go join your lines, go be the main character of your own terminal 💅🌈✨

📦 where this page comes from