Skip to Content
gnux

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 FILE2

GNU 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 join of two CSV files with -a 1 -a 2 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 newline

Examples

Combine a names list and an ages list that share an ID column

joinx names.txt ages.txt

Attach each order to its customer from two CSV exports

joinx -t, users.csv orders.csv

Look up customer names when the ID is the second column of the orders file

joinx -1 2 -2 1 orders.txt customers.txt

Keep everyone in the names list, even those with no age recorded

joinx -a 1 names.txt ages.txt

Find the tasks in the full list that are not marked done yet

joinx -v 1 all.txt done.txt

Merge two inventories into one table, marking missing values as NULL

joinx -a 1 -a 2 -e NULL -o auto a.txt b.txt

Build a report with just the columns you need, in your order

joinx -o 1.2,2.3,0 a.txt b.txt

Join two CSV exports that each start with a header row

joinx --header -t, users.csv orders.csv

Join two exports that came out of a database unsorted

sortx a.txt > a.sorted && sortx b.txt > b.sorted && joinx a.sorted b.sorted

Match user names written with different capitalization in two systems

joinx -i a.txt b.txt

Join the output of another command against a lookup file

sortx ids.txt | joinx - names.txt

Make 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 -a FILENUM, but suppress joined output lines.
  • -o, --output-format: Obey FORMAT while constructing output line.
  • --pretty: 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: Use CHAR as input and output field separator.
  • --theme: Color the view with the built-in theme NAME (gnux theme 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

StatusMeaning
0success: every operand was processed
1failure: 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

See also

On this page