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.

What is the join command?

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.

Examples

Join by the first field

After sorting the two files according to the same rule, they are joined.

join names.sorted scores.sorted

Specify a delimiter

Colon-separated files must use the same delimiter system in both inputs.

join -t ':' users.sorted roles.sorted

Display unmatched rows from the first file

If you want to see unmatched rows, add -a 1.

join -a 1 names.sorted scores.sorted

Result of joining on common fields

join basically merges rows where the first field of each file is the same. The following files are pre-sorted based on the first column, which is the join key.

printf 'a Ana\nb Bob\n' > names.txt
printf 'a 7\nb 12\n' > ages.txt
join names.txt ages.txt

Example output:

a Ana 7
b Bob 12

Input files should be sorted according to the same locale and key. Rows that do not match are omitted from the default output, so to check for missing keys, review -a 1 or -a 2. The two files in the example are created in the current directory, so after the work is done, check if they are needed and clean up.

Main Options and Format

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.