Linux join Command: Combine Files by a Common Field

join combines rows with the same key value from two text files into a single row. The difference from paste is that it joins based on field values, not row numbers.

By default, it uses the first field of each file as the key, and both files must be sorted by that key. The default behavior is to output only matching rows. To check for missing keys as well, review the -a or -v options.

Basic syntax

join [option] file1 file2

Installed implementations and options may vary depending on the distribution. Check your system's description with man join.

Prepare, sort, join, and inspect unmatched rows

Run the complete block: it prepares every input in a new temporary directory inside a subshell and prints that directory at the end. It does not overwrite files in the current working directory. Inspect the results and remove only the lab data when it is no longer needed.

(
set -eu
labdir=$(mktemp -d)
cd "$labdir"
printf 'b Bob
a Ana
c Cat
' > names.txt
printf 'a 7
b 12
' > scores.txt
LC_ALL=C sort -k1,1 names.txt > names.sorted
LC_ALL=C sort -k1,1 scores.txt > scores.sorted
LC_ALL=C join --check-order names.sorted scores.sorted
LC_ALL=C join --check-order -a 1 names.sorted scores.sorted
printf 'a:Ana
b:Bob
' > users.txt
printf 'a:reader
b:writer
' > roles.txt
LC_ALL=C sort -t ':' -k1,1 users.txt > users.sorted
LC_ALL=C sort -t ':' -k1,1 roles.txt > roles.sorted
LC_ALL=C join --check-order -t ':' users.sorted roles.sorted
printf 'Lab files: %s\n' "$labdir"
)

The first join prints a Ana 7 and b Bob 12. With -a 1, c Cat is also retained without a score. The colon example prints a:Ana:reader and b:Bob:writer. Keys are compared as strings and both sort and join use LC_ALL=C. Duplicate keys can produce every matching row combination, not a one-to-one join. Do not use partial output from a failed --check-order run as a completed result.

Main Options and Format

Options/Format Description
-t character Specifies the input/output field delimiter.
-1 N / -2 N Specifies the merge key fields for the first and second files.
-a 1 or -a 2 Also outputs unmatched rows from the specified file.
-v 1 or -v 2 Outputs only unmatched rows from the specified file.
-o format Specifies the output fields and order.

Precautions when using

Both files must be sorted by the same key, delimiter, and locale. Unsorted input may result in missing or incorrectly combined entries. If a key is duplicated, multiple output lines can be produced for a single key, so check the resulting count.

Frequently Asked Questions

Can an unsorted file be joined directly?

The usual join operation requires both files to be sorted by the joining field. Make a copy with the sorting order and locale matched before running.

Official Documentation

The exact behavior of the options and differences between implementations can be found in the official documentation for join.