join: add --header option to always output the first line

This essentially allows one to use --check-order with headings.
Note join without --check-order will already handle the common case
where headings do match in each file, however using --check-order will fail
often when the header sorts after the first line of data.

Note also that this will join header lines from each file even if
they don't match, with headings from the first file being used.

* NEWS: Mention the new option.
* doc/coreutils.texi (join invocation): Describe the new option.
* src/join.c (usage): Likewise.
(join): Join the header lines unconditionally.
* tests/misc/join: Add 5 new tests.

1 files changed, 9 insertions, 0 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 184b55a8c..2b3d32b94 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -5515,6 +5515,15 @@ Do not check that both input files are in sorted order.  This is the default.
 Replace those output fields that are missing in the input with
 @var{string}.
 
+@item --header
+@opindex --header
+Treat the first line of each input file as a header line. The header lines will
+be joined and printed as the first output line.  If @option{-o} is used to
+specify output format, the header line will be printed according to the
+specified format.  The header lines will not be checked for ordering even if
+@option{--check-order} is specified.  Also if the header lines from each file
+do not match, the heading fields from the first file will be used.
+
 @item -i
 @itemx --ignore-case
 @opindex -i