joinx
Join lines of two files on a common field.
Mirrors GNU join. Run it as joinx, or as gnux joinx.
Synopsis
joinx [OPTION]... FILE1 FILE2GNU reference
Description
joinx prints, for each pair of input lines with identical join fields, one line made of the join field followed by the remaining fields of both lines. By default the join field is the first, fields are separated by blanks (leading blanks are ignored) and output fields by a single space. Either FILE may be - for standard input, but not both. Both files must be sorted on the join field, as sortx (or LC_ALL=C sort) sorts them; lines are compared byte by byte, as in the C locale, whatever LANG says. -1 FIELD and -2 FIELD pick the join field of each file and -j FIELD both. -a FILENUM also prints the unpairable lines of that file, and -v FILENUM prints only them. -o FORMAT lists the output fields as FILENUM.FIELD or 0 (the join field), separated by commas or blanks; -o auto takes the number of fields from the first line of each file. -e EMPTY fills missing fields. -t CHAR separates fields on input and output with CHAR, and -t '' makes the whole line one field. -i ignores case when comparing join fields. --header pairs the first lines of the files as headers without checking their order. By default joinx warns once per file when it finds a line out of order after an unpairable line and then exits with status 1; --check-order fails at the first line out of order, and --nocheck-order never checks. -z makes NUL the line delimiter. When both --check-order and --nocheck-order are given, --check-order wins. GNU's obsolescent -j1 FIELD and -j2 FIELD forms are not accepted; use -1 and -2.
gnux's terminal view (BR-13): on a terminal, each field is in the color of the file it came from, and the join field in a color of its own when the line pairs both files; a --header line is in the header color. The text is GNU's. --pretty[=WHEN] and --theme=NAME, options of gnux's own, choose the view (GNUX_PRETTY, GNUX_THEME); -z and piped or redirected output are always GNU's.
Permissions
Needs read permission on FILE1 and FILE2 and search permission on the directories leading to them. Nothing is ever modified.
Use cases
- Combining two tables that share a key column, like a relational
join. - Attaching names to IDs, or prices to product codes, from a lookup file.
- Finding the keys present in one list but missing from another with
-v. - Building a full outer
joinof two CSV files with-a1-a2 and-e. - Merging two reports on a column other than the first with -1 and -2.
Flags
--check-order check that the input is correctly sorted, even if all input lines are pairable
-e, --empty EMPTY replace missing input fields with EMPTY
-1, --field1 FIELD join on this FIELD of file 1
-2, --field2 FIELD join on this FIELD of file 2
--header treat the first line in each file as field headers, print them without trying to pair them
--help display this help and exit
-i, --ignore-case ignore differences in case when comparing fields
-j, --join-field stringArray equivalent to '-1 FIELD -2 FIELD'
--nocheck-order do not check that the input is correctly sorted
-v, --only-unpaired stringArray like -a FILENUM, but suppress joined output lines
-o, --output-format FORMAT obey FORMAT while constructing output line
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
-t, --separator CHAR use CHAR as input and output field separator
--theme NAME color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
-a, --unpaired FILENUM also print unpairable lines from file FILENUM, where FILENUM is 1 or 2
--version output version information and exit
-z, --zero-terminated line delimiter is NUL, not newlineExamples
Combine a names list and an ages list that share an ID column
joinx names.txt ages.txtAttach each order to its customer from two CSV exports
joinx -t, users.csv orders.csvLook up customer names when the ID is the second column of the orders file
joinx -1 2 -2 1 orders.txt customers.txtKeep everyone in the names list, even those with no age recorded
joinx -a 1 names.txt ages.txtFind the tasks in the full list that are not marked done yet
joinx -v 1 all.txt done.txtMerge two inventories into one table, marking missing values as NULL
joinx -a 1 -a 2 -e NULL -o auto a.txt b.txtBuild a report with just the columns you need, in your order
joinx -o 1.2,2.3,0 a.txt b.txtJoin two CSV exports that each start with a header row
joinx --header -t, users.csv orders.csvJoin two exports that came out of a database unsorted
sortx a.txt > a.sorted && sortx b.txt > b.sorted && joinx a.sorted b.sortedMatch user names written with different capitalization in two systems
joinx -i a.txt b.txtJoin the output of another command against a lookup file
sortx ids.txt | joinx - names.txtMake a script stop if an input was not sorted, rather than miss matches
joinx --check-order a.txt b.txt || echox 'not sorted'Count matched orders in the portable gnux shell, the same on every OS
gnux shell -c 'joinx -t, users.csv orders.csv | wcx -l'Options
Each option has a page of its own, with its usage and examples.
- --check-order: Check that the input is correctly sorted, even if all input lines are pairable.
- -e, --empty: Replace missing input fields with EMPTY.
- -1, --field1: Join on this FIELD of file 1.
- -2, --field2: Join on this FIELD of file 2.
- --header: Treat the first line in each file as field headers, print them without trying to pair them.
- -i, --ignore-case: Ignore differences in case when comparing fields.
- -j, --join-field: Equivalent to '-1 FIELD -2 FIELD'.
- --nocheck-order: Do not check that the input is correctly sorted.
- -v, --only-unpaired: Like
-aFILENUM, but suppress joined output lines. - -o, --output-format: Obey FORMAT while constructing output line.
- --pretty: The
gnuxterminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default. - -t, --separator: Use CHAR as input and output field separator.
- --theme: Color the view with the built-in theme NAME (
gnuxtheme picks and saves one); GNUX_THEME sets the default. - -a, --unpaired: Also print unpairable lines from file FILENUM, where FILENUM is 1 or 2.
- -z, --zero-terminated: Line delimiter is NUL, not newline.
Exit status
| Status | Meaning |
|---|---|
| 0 | success: every operand was processed |
| 1 | failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake |
Help in the terminal
joinx --help # options, first examples, exit status
gnux help joinx # this page: the full manual
gnux help joinx --OPTION # one option in depth, with its examples