man pages section 1: User Commands

Exit Print View

Updated: July 2014

join (1g)


join - join lines of two files on a common field


join [OPTION]... FILE1 FILE2


User Commands                                             JOIN(1)

     join - join lines of two files on a common field

     join [OPTION]... FILE1 FILE2

     For  each  pair  of  input lines with identical join fields,
     write a line to standard output.  The default join field  is
     the  first,  delimited  by  whitespace.  When FILE1 or FILE2
     (not both) is -, read standard input.

     -a FILENUM
          also print unpairable lines from  file  FILENUM,  where
          FILENUM is 1 or 2, corresponding to FILE1 or FILE2

     -e EMPTY
          replace missing input fields with EMPTY

     -i, --ignore-case
          ignore differences in case when comparing fields

     -j FIELD
          equivalent to '-1 FIELD -2 FIELD'

     -o FORMAT
          obey FORMAT while constructing output line

     -t CHAR
          use CHAR as input and output field separator

     -v FILENUM
          like -a FILENUM, but suppress joined output lines

     -1 FIELD
          join on this FIELD of file 1

     -2 FIELD
          join on this FIELD of file 2

          check  that  the input is correctly sorted, even if all
          input lines are pairable

          do not check that the input is correctly sorted

          treat the first line in each  file  as  field  headers,
          print them without trying to pair them


GNU coreutils 8.16   Last change: March 2012                    1

User Commands                                             JOIN(1)

          display this help and exit

          output version information and exit

     Unless  -t CHAR is given, leading blanks separate fields and
     are ignored, else fields are separated by CHAR.   Any  FIELD
     is  a  field  number  counted from 1.  FORMAT is one or more
     comma  or  blank  separated   specifications,   each   being
     'FILENUM.FIELD'  or  '0'.   Default  FORMAT outputs the join
     field, the remaining fields from FILE1, the remaining fields
     from FILE2, all separated by CHAR.  If FORMAT is the keyword
     'auto', then the first line of each file determines the num-
     ber of fields output for each line.

     Important:  FILE1  and  FILE2  must  be  sorted  on the join
     fields.  E.g., use "sort -k 1b,1" if 'join' has no  options,
     or use "join -t ''" if 'sort' has no options.  Note, compar-
     isons honor the rules specified  by  'LC_COLLATE'.   If  the
     input is not sorted and some lines cannot be joined, a warn-
     ing message will be given.

     Written by Mike Haertel.

     Report join bugs to
     GNU coreutils home page:  <
     General  help  using GNU software: <
     Report  join  translation  bugs  to  <http://translationpro->

     Copyright  (C)  2012 Free Software Foundation, Inc.  License
     GPLv3+:     GNU     GPL     version     3      or      later
     This  is  free  software:  you are free to change and redis-
     tribute it.  There is NO WARRANTY, to the  extent  permitted
     by law.

     See   attributes(5)   for   descriptions  of  the  following

GNU coreutils 8.16   Last change: March 2012                    2

User Commands                                             JOIN(1)

     |Availability   | file/gnu-coreutils |
     |Stability      | Uncommitted        |
     comm(1), uniq(1)

     The full documentation for join is maintained as  a  Texinfo
     manual.    If  the  info  and  join  programs  are  properly
     installed at your site, the command

          info coreutils 'join invocation'

     should give you access to the complete manual.

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

GNU coreutils 8.16   Last change: March 2012                    3