JOIN(1)

📦
version 9.12 · 29 versions
, in arch rolling

💖 join — okay bestie, let's talk

so the manual name is join (it lives in section 1, user commands, in case anyone asks) and it does exactly one iconic thing: it takes lines from two files and glues them together when they share a common field. that's it. that's the whole vibe. ✨

🌸 SYNOPSIS 🌸

join [OPTION]... FILE1 FILE2

🦋 DESCRIPTION 🦋

okay so picture this: you've got two files, right? for every pair of input lines that have identical join fields, join writes a line out to standard output. and the default join field — like, the one it uses if you don't say otherwise — is the first field, and fields are delimited by blanks. easy. slay.

and here's a lil treat: if FILE1 or FILE2 (not both, bestie, pick one) is -, then it reads standard input. 🫶

now. the options. there are a lot of them and honestly they're all kind of iconic, so let's go:

  • -a FILENUM — also print the unpairable lines from file FILENUM, where FILENUM is 1 or 2, matching up to FILE1 or FILE2. so like, the leftovers get to come to the party too 💅
  • -e STRING — replace missing (empty) input fields with STRING. i.e., the missing fields you specified with the '-12jo' options. no field left behind 💖
  • -i, --ignore-case — ignore differences in case when comparing fields. uppercase, lowercase, we don't care, we're chill like that ✨
  • -j FIELD — literally just equivalent to '-1 FIELD -2 FIELD'. a shortcut, a little timesaver, we love her
  • -o FORMAT — obey FORMAT while constructing the output line. you're in charge of the fit now 👑
  • -t CHAR — use CHAR as the input and output field separator
  • -v FILENUM — like -a FILENUM, but suppress the joined output lines. only the loners, none of the couples 🙈
  • -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's doing a vibe check on your sort fr fr
  • --nocheck-order — do not check that the input is correctly sorted. live your truth, no vibe check today
  • --header — treat the first line in each file as field headers, print them without trying to pair them. respect the headers, they're the main characters 🎀
  • -z, --zero-terminated — line delimiter is NUL, not newline
  • --help — display this help and exit
  • --version — output version information and exit

okay now the details, because this is where it gets real:

unless -t CHAR is given, leading blanks separate fields and are ignored. otherwise, fields are separated by CHAR. any FIELD is a field number counted from 1 (not 0, bestie, this isn't that kind of program).

FORMAT is one or more comma or blank separated specifications, and each one is either '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. cute, right? 🌈

Important: FILE1 and FILE2 must be sorted on the join fields. this is not a suggestion, this is the law 😭 for example, 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. sort your files. please. for me. 💀

👑 AUTHOR 👑

Written by Mike Haertel. legend behavior, honestly.

😭 REPORTING BUGS 😭

found something cursed? tell the people:

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. (ngl that part is important, don't skip it 🫶)

🌟 SEE ALSO 🌟

and that's the whole page, bestie 💅 this was GNU coreutils 9.12, dated September 2026 — go forth and join your lines, and remember: sort first, slay always. 🦋✨

📦 where this page comes from