Here-documents

Here-documents are a type of redirection that lets you provide multi-line input directly within a script or command line. They are useful for supplying input to commands or scripts without creating a separate file.

Syntax

A here-document starts with the << operator followed by a delimiter word. After the next newline operator, the shell reads lines until it finds a line containing only the delimiter (with no trailing blanks). The lines read become the standard input for the command.

$ cat <<EOF
> Hello,
> World!
> EOF
Hello,
World!

In this example, EOF is the delimiter. The cat utility receives the lines between <<EOF and the final EOF.

POSIX allows any word as a delimiter, but for portability, use only alphanumeric characters and underscores. Delimiters with special characters or whitespace can cause unexpected behavior, especially if not quoted. See also Quoting the delimiter and expanding the content below for the effects of quoting the delimiter.

Multiple here-documents

You can use multiple here-document operators in a single command or across multiple commands on the same line. After the next newline, the shell reads lines for each here-document in order, stopping at each delimiter.

$ cat <<EOF; cat <<END <<EOF
> Hello,
> EOF
> This is the first here-document for the second command.
> END
> World!
> EOF
Hello,
World!

Here-documents in command substitution

When using a here-document inside command substitution, the content must be included within the substitution syntax:

$ echo $(cat <<EOF
> Hello,
> World!
> EOF
> )
Hello, World!

It is not supported to place the here-document content outside the command substitution, as in:

echo $(cat <<EOF)
Hello,
World!
EOF

Automatic removal of leading tabs

If you use <<- instead of <<, all leading tab characters are removed from the here-document content and the delimiter line. This allows you to indent here-documents in your scripts for readability, without affecting the output.

$ cat <<-EOF
> 		Hello,
> 		World!
> 	EOF
Hello,
World!

Note: Only leading tabs are removed, not spaces.

Quoting the delimiter and expanding the content

If the delimiter after the redirection operator is quoted, quote removal is performed on the delimiter, and the result is used to find the end of the here-document. In this case, the content is not subject to any expansions and is treated literally.

$ user="Alice"
$ cat <<'EOF'
> Hello, $user!
> 1 + 1 = $((1 + 1)).
> EOF
Hello, $user!
1 + 1 = $((1 + 1)).

If the delimiter is not quoted, the following are handled in the here-document content when the redirection is performed:

• Backslash escapes work only before $, `, and \. Other backslashes are literal.
• Line continuations are removed.
• Parameter expansion, command substitution, and arithmetic expansion are performed.

Single and double quotes in the here-document content are treated literally.

$ user="Alice"
$ cat <<EOF
> Hello, $user!
> 1 + 1 = $((1 + 1)).
> EOF
Hello, Alice!
1 + 1 = 2.