{
    "mode": "info",
    "parameter": "join",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/join/json",
    "generated": "2026-07-29T18:14:55Z",
    "sections": {
        "File: coreutils.info,  Node: join invocation,  Prev: paste invocation,  Up: Operating on fields": {
            "content": "",
            "subsections": [
                {
                    "name": "8.3 'join': Join lines on a common field",
                    "content": "'join' writes to standard output a line for each pair of input lines\nthat have identical join fields.  Synopsis:\n\njoin [OPTION]... FILE1 FILE2\n\nEither FILE1 or FILE2 (but not both) can be '-', meaning standard\ninput.  FILE1 and FILE2 should be sorted on the join fields.\n\n$ cat file1\na 1\nb 2\ne 5\n\n$ cat file2\na X\ne Y\nf Z\n\n$ join file1 file2\na 1 X\ne 5 Y\n\n'join''s default behavior (when no options are given):\n* the join field is the first field in each line;\n* fields in the input are separated by one or more blanks, with\nleading blanks on the line ignored;\n* fields in the output are separated by a space;\n* each output line consists of the join field, the remaining fields\nfrom FILE1, then the remaining fields from FILE2.\n\n* Menu:\n\n* General options in join::      Options which affect general program behavior.\n* Sorting files for join::       Using 'sort' before 'join'.\n* Working with fields::          Joining on different fields.\n* Paired and unpaired lines::    Controlling 'join''s field matching.\n* Header lines::                 Working with header lines in files.\n* Set operations::               Union, Intersection and Difference of files.\n"
                }
            ]
        },
        "File: coreutils.info,  Node: General options in join,  Next: Sorting files for join,  Up: join invocation": {
            "content": "The program accepts the following options.  Also see *note Common\noptions::.\n\n'-a FILE-NUMBER'\nPrint a line for each unpairable line in file FILE-NUMBER (either\n'1' or '2'), in addition to the normal output.\n\n'--check-order'\nFail with an error message if either input file is wrongly ordered.\n\n'--nocheck-order'\nDo not check that both input files are in sorted order.  This is\nthe default.\n\n'-e STRING'\nReplace those output fields that are missing in the input with\nSTRING.  I.e., missing fields specified with the '-12jo' options.\n\n'--header'\nTreat the first line of each input file as a header line.  The\nheader lines will be joined and printed as the first output line.\nIf '-o' is used to specify output format, the header line will be\nprinted according to the specified format.  The header lines will\nnot be checked for ordering even if '--check-order' is specified.\nAlso if the header lines from each file do not match, the heading\nfields from the first file will be used.\n\n'-i'\n'--ignore-case'\nIgnore differences in case when comparing keys.  With this option,\nthe lines of the input files must be ordered in the same way.  Use\n'sort -f' to produce this ordering.\n\n'-1 FIELD'\nJoin on field FIELD (a positive integer) of file 1.\n\n'-2 FIELD'\nJoin on field FIELD (a positive integer) of file 2.\n\n'-j FIELD'\nEquivalent to '-1 FIELD -2 FIELD'.\n\n'-o FIELD-LIST'\n'-o auto'\nIf the keyword 'auto' is specified, infer the output format from\nthe first line in each file.  This is the same as the default\noutput format but also ensures the same number of fields are output\nfor each line.  Missing fields are replaced with the '-e' option\nand extra fields are discarded.\n\nOtherwise, construct each output line according to the format in\nFIELD-LIST.  Each element in FIELD-LIST is either the single\ncharacter '0' or has the form M.N where the file number, M, is '1'\nor '2' and N is a positive field number.\n\nA field specification of '0' denotes the join field.  In most\ncases, the functionality of the '0' field spec may be reproduced\nusing the explicit M.N that corresponds to the join field.\nHowever, when printing unpairable lines (using either of the '-a'\nor '-v' options), there is no way to specify the join field using\nM.N in FIELD-LIST if there are unpairable lines in both files.  To\ngive 'join' that functionality, POSIX invented the '0' field\nspecification notation.\n\nThe elements in FIELD-LIST are separated by commas or blanks.\nBlank separators typically need to be quoted for the shell.  For\nexample, the commands 'join -o 1.2,2.2' and 'join -o '1.2 2.2'' are\nequivalent.\n\nAll output lines--including those printed because of any -a or -v\noption--are subject to the specified FIELD-LIST.\n\n'-t CHAR'\nUse character CHAR as the input and output field separator.  Treat\nas significant each occurrence of CHAR in the input file.  Use\n'sort -t CHAR', without the '-b' option of 'sort', to produce this\nordering.  If 'join -t ''' is specified, the whole line is\nconsidered, matching the default operation of sort.  If '-t '\\0''\nis specified then the ASCII NUL character is used to delimit the\nfields.\n\n'-v FILE-NUMBER'\nPrint a line for each unpairable line in file FILE-NUMBER (either\n'1' or '2'), instead of the normal output.\n\n'-z'\n'--zero-terminated'\nDelimit items with a zero byte rather than a newline (ASCII LF).\nI.e., treat input as items separated by ASCII NUL and terminate\noutput items with ASCII NUL. This option can be useful in\nconjunction with 'perl -0' or 'find -print0' and 'xargs -0' which\ndo the same in order to reliably handle arbitrary file names (even\nthose containing blanks or other special characters).  Note with\n'-z' the newline character is treated as a field separator.\n\nAn exit status of zero indicates success, and a nonzero value\nindicates failure.\n\nIf the '--check-order' option is given, unsorted inputs will cause a\nfatal error message.  If the option '--nocheck-order' is given, unsorted\ninputs will never cause an error message.  If neither of these options\nis given, wrongly sorted inputs are diagnosed only if an input file is\nfound to contain unpairable lines, and when both input files are non\nempty.  If an input file is diagnosed as being unsorted, the 'join'\ncommand will exit with a nonzero status (and the output should not be\nused).\n\nForcing 'join' to process wrongly sorted input files containing\nunpairable lines by specifying '--nocheck-order' is not guaranteed to\nproduce any particular output.  The output will probably not correspond\nwith whatever you hoped it would be.\n",
            "subsections": []
        },
        "File: coreutils.info,  Node: Sorting files for join,  Next: Working with fields,  Prev: General options in join,  Up: join invocation": {
            "content": "'join' requires sorted input files.  Each input file should be sorted\naccording to the key (=field/column number) used in 'join'.  The\nrecommended sorting option is 'sort -k 1b,1' (assuming the desired key\nis in the first column).\n\nTypical usage:\n$ sort -k 1b,1 file1 > file1.sorted\n$ sort -k 1b,1 file2 > file2.sorted\n$ join file1.sorted file2.sorted > file3\n\nNormally, the sort order is that of the collating sequence specified\nby the 'LCCOLLATE' locale.  Unless the '-t' option is given, the sort\ncomparison ignores blanks at the start of the join field, as in 'sort\n-b'.  If the '--ignore-case' option is given, the sort comparison\nignores the case of characters in the join field, as in 'sort -f':\n\n$ sort -k 1bf,1 file1 > file1.sorted\n$ sort -k 1bf,1 file2 > file2.sorted\n$ join --ignore-case file1.sorted file2.sorted > file3\n\nThe 'sort' and 'join' commands should use consistent locales and\noptions if the output of 'sort' is fed to 'join'.  You can use a command\nlike 'sort -k 1b,1' to sort a file on its default join field, but if you\nselect a non-default locale, join field, separator, or comparison\noptions, then you should do so consistently between 'join' and 'sort'.\n",
            "subsections": []
        },
        "To avoid any locale-related issues, it is recommended to use the 'C'": {
            "content": "locale for both commands:\n\n$ LCALL=C sort -k 1b,1 file1 > file1.sorted\n$ LCALL=C sort -k 1b,1 file2 > file2.sorted\n$ LCALL=C join file1.sorted file2.sorted > file3\n",
            "subsections": []
        },
        "File: coreutils.info,  Node: Working with fields,  Next: Paired and unpaired lines,  Prev: Sorting files for join,  Up: join invocation": {
            "content": "",
            "subsections": []
        },
        "Use '-1','-2' to set the key fields for each of the input files.  Ensure": {
            "content": "the preceding 'sort' commands operated on the same fields.\n",
            "subsections": []
        },
        "The following example joins two files, using the values from seventh": {
            "content": "field of the first file and the third field of the second file:\n\n$ sort -k 7b,7 file1 > file1.sorted\n$ sort -k 3b,3 file2 > file2.sorted\n$ join -1 7 -2 3 file1.sorted file2.sorted > file3\n\nIf the field number is the same for both files, use '-j':\n\n$ sort -k4b,4 file1 > file1.sorted\n$ sort -k4b,4 file2 > file2.sorted\n$ join -j4    file1.sorted file2.sorted > file3\n",
            "subsections": []
        },
        "Both 'sort' and 'join' operate of whitespace-delimited fields.  To": {
            "content": "specify a different delimiter, use '-t' in both:\n\n$ sort -t, -k3b,3 file1 > file1.sorted\n$ sort -t, -k3b,3 file2 > file2.sorted\n$ join -t, -j3    file1.sorted file2.sorted > file3\n\nTo specify a tab (ASCII 0x09) character instead of whitespace, use (1):\n\n$ sort -t$'\\t' -k3b,3 file1 > file1.sorted\n$ sort -t$'\\t' -k3b,3 file2 > file2.sorted\n$ join -t$'\\t' -j3    file1.sorted file2.sorted > file3\n",
            "subsections": []
        },
        "If 'join -t ''' is specified then the whole line is considered which": {
            "content": "matches the default operation of sort:\n\n$ sort file1 > file1.sorted\n$ sort file2 > file2.sorted\n$ join -t '' file1.sorted file2.sorted > file3\n\n---------- Footnotes ----------\n\n(1) the '$'\\t'' is supported in most modern shells.  For older\nshells, use a literal tab\n",
            "subsections": []
        },
        "File: coreutils.info,  Node: Paired and unpaired lines,  Next: Header lines,  Prev: Working with fields,  Up: join invocation": {
            "content": "",
            "subsections": []
        },
        "In this section the 'sort' commands are omitted for brevity.  Sorting": {
            "content": "the files before joining is still required.\n\n'join''s default behavior is to print only lines common to both input\nfiles.  Use '-a' and '-v' to print unpairable lines from one or both\nfiles.\n\nAll examples below use the following two (pre-sorted) input files:\n\n$ cat file1                          $ cat file2\na 1                                  a A\nb 2                                  c C\n",
            "subsections": []
        },
        "Command                              Outcome": {
            "content": "--------------------------------------------------------------------------\n$ join file1 file2              common lines (intersection)\na 1 A\n$ join -a 1 file1 file2         common lines and unpaired lines\na 1 A                           from the first file\nb 2\n$ join -a 2 file1 file2         common lines and unpaired lines\na 1 A                           from the second file\nc C\n$ join -a 1 -a 2 file1 file2    all lines (paired and unpaired)\na 1 A                           from both files (union).\nb 2                             see note below regarding '-o\nc C                             auto'.\n\n$ join -v 1 file1 file2         unpaired lines from the first file\nb 2                             (difference)\n\n$ join -v 2 file1 file2         unpaired lines from the second\nc C                             file (difference)\n\n$ join -v 1 -v 2 file1 file2    unpaired lines from both files,\nb 2                             omitting common lines (symmetric\nc C                             difference).\n\n\nThe '-o auto -e X' options are useful when dealing with unpaired lines.",
            "subsections": []
        },
        "The following example prints all lines (common and unpaired) from both": {
            "content": "files.  Without '-o auto' it is not easy to discern which fields\noriginate from which file:\n\n$ join -a 1 -a 2 file1 file2\na 1 A\nb 2\nc C\n\n$ join -o auto -e X -a 1 -a 2 file1 file2\na 1 A\nb 2 X\nc X C\n\nIf the input has no unpairable lines, a GNU extension is available;\nthe sort order can be any order that considers two fields to be equal if\nand only if the sort comparison described above considers them to be\nequal.  For example:\n\n$ cat file1\na a1\nc c1\nb b1\n\n$ cat file2\na a2\nc c2\nb b2\n\n$ join file1 file2\na a1 a2\nc c1 c2\nb b1 b2\n",
            "subsections": []
        },
        "File: coreutils.info,  Node: Header lines,  Next: Set operations,  Prev: Paired and unpaired lines,  Up: join invocation": {
            "content": "",
            "subsections": []
        },
        "The '--header' option can be used when the files to join have a header": {
            "content": "line which is not sorted:\n\n$ cat file1\nName     Age\nAlice    25\nCharlie  34\n\n$ cat file2\nName   Country\nAlice  France\nBob    Spain\n\n$ join --header -o auto -e NA -a1 -a2 file1 file2\nName     Age   Country\nAlice    25    France\nBob      NA    Spain\nCharlie  34    NA\n\nTo sort a file with a header line, use GNU 'sed -u'.  The following\nexample sort the files but keeps the first line of each file in place:\n\n$ ( sed -u 1q ; sort -k2b,2 ) < file1 > file1.sorted\n$ ( sed -u 1q ; sort -k2b,2 ) < file2 > file2.sorted\n$ join --header -o auto -e NA -a1 -a2 file1.sorted file2.sorted > file3\n",
            "subsections": []
        },
        "File: coreutils.info,  Node: Set operations,  Prev: Header lines,  Up: join invocation": {
            "content": "",
            "subsections": []
        },
        "Combine 'sort', 'uniq' and 'join' to perform the equivalent of set": {
            "content": "operations on files:\n\n'sort -u file1 file2'                Union of unsorted files\n\n'sort file1 file2 | uniq -d'         Intersection of unsorted files\n\n'sort file1 file1 file2 | uniq -u'   Difference of unsorted files\n\n'sort file1 file2 | uniq -u'         Symmetric Difference of unsorted\nfiles\n\n'join -t '' -a1 -a2 file1 file2'     Union of sorted files\n\n'join -t '' file1 file2'             Intersection of sorted files\n\n'join -t '' -v2 file1 file2'         Difference of sorted files\n\n'join -t '' -v1 -v2 file1 file2'     Symmetric Difference of sorted\nfiles\n\n\nAll examples above operate on entire lines and not on specific\nfields: 'sort' without '-k' and 'join -t ''' both consider entire lines\nas the key.\n",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}