Previous: paste invocation, Up: Operating on fields
join writes to standard output a line for each pair of input lines that have identical join fields. Synopsis:
join [option]... file1 file2
Either file1 or file2 (but not both) can be ‘-’, meaning standard input. file1 and file2 should be sorted on the join fields.
Normally, the sort order is that of the
collating sequence specified by the LC_COLLATE locale. Unless
the -t option is given, the sort comparison ignores blanks at
the start of the join field, as in
sort -b. If the
--ignore-case option is given, the sort comparison ignores
the case of characters in the join field, as in
The sort and join commands should use consistent locales and options if the output of sort is fed to join. You can use a command like ‘sort -k 1b,1’ to sort a file on its default join field, but if you select a non-default locale, join field, separator, or comparison options, then you should do so consistently between join and sort. If ‘join -t ''’ is specified then the whole line is considered which matches the default operation of sort.
If the input has no unpairable lines, a GNU extension is available; the sort order can be any order that considers two fields to be equal if and only if the sort comparison described above considers them to be equal. For example:
$ cat file1 a a1 c c1 b b1 $ cat file2 a a2 c c2 b b2 $ join file1 file2 a a1 a2 c c1 c2 b b1 b2
If the --check-order option is given, unsorted inputs will cause a fatal error message. If the option --nocheck-order is given, unsorted inputs will never cause an error message. If neither of these options is given, wrongly sorted inputs are diagnosed only if an input file is found to contain unpairable lines, and when both input files are non empty. If an input file is diagnosed as being unsorted, the join command will exit with a nonzero status (and the output should not be used).
Forcing join to process wrongly sorted input files containing unpairable lines by specifying --nocheck-order is not guaranteed to produce any particular output. The output will probably not correspond with whatever you hoped it would be.
The defaults are:
The program accepts the following options. Also see Common options.
Otherwise, construct each output line according to the format in field-list. Each element in field-list is either the single character ‘0’ or has the form m.n where the file number, m, is ‘1’ or ‘2’ and n is a positive field number.
A field specification of ‘0’ denotes the join field. In most cases, the functionality of the ‘0’ field spec may be reproduced using the explicit m.n that corresponds to the join field. However, when printing unpairable lines (using either of the -a or -v options), there is no way to specify the join field using m.n in field-list if there are unpairable lines in both files. To give join that functionality, POSIX invented the ‘0’ field specification notation.
The elements in field-list are separated by commas or blanks. Blank separators typically need to be quoted for the shell. For example, the commands ‘join -o 1.2,2.2’ and ‘join -o '1.2 2.2'’ are equivalent.
All output lines—including those printed because of any -a or -v
option—are subject to the specified field-list.
An exit status of zero indicates success, and a nonzero value indicates failure.