join — Join files on a field

Linux / Basic Linux commands / join.html

Combines two text files on a shared key field.

Basic Information

What is this command?

join merges lines from two files that share a key, similar to a database join. Both inputs must be sorted by the key for correct results.

-1 and -2 select the key field in each file, -t sets the separator and -a includes unmatched lines. For unsorted input, sort both files with a matching separator first.

What problems does it solve?

• Combining two lists by user ID
• Merging two CSV files on a shared key
• Finding entries present in only one file
• Key-based merging that paste cannot do

Key features

Key-based merge

Merges lines that share a key.

• When to use: Linking two lists by ID
• What you get: Reproduces relational joins on flat files.
• Limitations: Unsorted keys produce wrong output.

Field selection

-1 and -2 choose the key field per file.

• When to use: When the key is not the first column
• What you get: Join while keeping the original layout.
• Limitations: A wrong field index yields empty output.

Including unmatched

-a1, -a2 and -v control unmatched lines.

• When to use: Auditing missing entries
• What you get: You can inspect set differences.
• Limitations: Empty fields require interpretation.

Installation and usage

Check whether it is installed

join --version

sudo apt install coreutils # Debian/Ubuntu sudo dnf install coreutils # Fedora

Real-world examples

Basic join

Join on the first field.

sort users.txt -o u.txt
sort mail.txt -o m.txt
join u.txt m.txt

Custom separator

Join comma-separated files.

sort -t, -k1,1 a.csv -o a.s
sort -t, -k1,1 b.csv -o b.s
join -t, a.s b.s

Unmatched entries

Print keys only present on the left.

join -v1 u.txt m.txt | head