Here Document and Here String

1. Overview

In this tutorial, we’ll be taking a look at the syntax of Linux’s here document and here string. In addition to that, we’ll also demonstrate several common usage patterns associated with them.

2. Definition

In Linux, here document (also commonly referred to as heredoc) refers to a special block of code that contains multi-line strings that will be redirected to a command. On the other hand, here string is a simpler version of heredoc, offering somewhat similar functionality, albeit not as powerful as the latter.

To understand the benefits of using either one, imagine that we want to send several lines of command over ssh to another remote system. In addition to that, let’s assume that the command needs to be sent without an interactive terminal. We can easily achieve that with the following:

ssh -T [email protected] "touch log1.txt"
ssh -T [email protected] "touch log2.txt"

In the trivial example above, we’re executing two lines of code over ssh on the remote system. However, if we’ve more commands to execute, the solution above will become cluttered and verbose. To make it more succinct, we can replace it with a heredoc:

ssh -T [email protected] << EOF
touch log1.txt
touch log2.txt
EOF

The command above is doing the same thing as the previous command in a much more concise form.

3. Here Document

3.1. Syntax

A heredoc consists of the ‘<<‘ redirection operator, followed by a delimiter token. After the delimiter token, lines of string can be defined to form the content. Finally, the delimiter token is placed at the end to serve as the termination. The delimiter token can be any value as long as it is unique enough that it won’t appear within the content. For example, we can create a heredoc that consists of several lines of simple string and have it output by the command cat:

cat <<EOF
This is line1
Another line
Finally 3rd line
EOF

In this example, we’ve defined the delimiter token as “EOF”. On the other hand, the three lines of string that are sandwiched between the pair of “EOF” tokens serve as the content. Then, those three strings are fed into the cat command, which will then print them to the console.

Do take note that the delimiter token will not be in the output of the heredoc.

3.2. Tab Suppression

Commonly, we add indentations to our heredoc with tabs so that it is much easier to read, especially in a shell script. However, rarely do we want the tabs to be part of the output. To suppress the tab indentations in the output, we can prefix the redirection operator ‘<<‘ with a dash symbol.

Concretely, if we do the following:

cat <<-EOF
    This message is indented
        This message is double indented
EOF

We’ll get the following output on our console:

This message is indented
This message is double indented

However, white spaces will not be suppressed even with the dash prefix.

3.3. Here Document With Parameter Substitution

We can also parameterize a heredoc by using variables, thereby making it dynamic. For example, we can change the output of a heredoc based on the value of a parameter:

cat <<EOF
Hello ${USER}
EOF

The output will then be customized based on the value of the variable USER.

3.4. Here Document With Command Substitution

In addition to parameters, heredoc also supports command substitution in its content. For example, let’s say we want to customize the output such that it always prints the current date and time:

cat <<EOF
Hello! It is currently: $(date)
EOF

Now, whenever we run the command above, the output will always have the current date and time.

3.5. Passing Arguments to Function With Here Document

We can also make use of heredoc to pass arguments to a function that otherwise requires interactive user input. For example, let’s consider the following function:

LoginToModule()
{
    read -p "Username: " username
    read -p "Passphrase: " passphrase
    echo "Obtained input ${username} and ${passphrase}"
}

When invoked, the function will wait for the user’s input to capture the value for the variables username and passphrase:

LoginToModule
Username: baeldung
Passphrase: secret
Obtained input baeldung and secret

Other than supplying the input interactively, we can construct a heredoc to pass the values:

LoginToModule <<EOF
adminuser
adminpassphrase
EOF

3.6. Escape Special Characters in Here Document

By default, the special characters like $, \, and ` are interpreted in heredoc so that functionality like parameter and command substitution could work. To escape them, we can prefix the special character with a backslash ‘\’:

cat <<EOF
Some Special Characters: \$ \\ \`
EOF

In the case that we want to escape all the special characters, we can either quote the delimiter token or prefix the delimiter token with a backslash.

The three different ways of escaping all the special characters are:

cat <<'EOF'
Some Special Characters: $ \ `
EOF

cat <<"EOF"
Some Special Characters: $ \ `
EOF

cat <<\EOF
Some Special Characters: $ \ `
EOF

One important thing to note is that when all the special characters are escaped, parameter and command substitution will no longer work. The reason is that the special characters that are used in parameter and command substitution will be escaped, not interpreted.

3.7. Disable Block of Code Using Here Document

In a shell script, one way to disable a block of code is to prefix every line of the code with a ‘#’ to make them into comments. However, we can do it much more efficiently using heredoc with the dummy command ‘:’. For example, we can disable several lines of code in our shell script:

#!/bin/bash
# disable-with-heredoc.sh

: <<'DISABLED'
echo "This line will not show up in the console.
echo "Neither will this line.
DISABLED

echo "This line will be printed to the console

By turning a block of code into a heredoc and redirecting it to the dummy command ‘:’, we’ve essentially prevented the block of code from executing. We’ve enclosed the delimiter token to escape all the special characters in the content. This is done to prevent any command substitution from being executed, thereby preventing any unintended side effects.

4. Here String

Here string is very similar to a heredoc, except that the former is a much simpler version of heredoc. For that reason, here string does not need a delimiter token. It is usually preferred whenever we need a quick way to redirect some strings into a command.

4.1. Syntax

To construct a here string, we use “<<<” operator to redirect a string into a command. Concretely, the syntax is:

COMMAND <<< $VAR

What it essentially does is expanding the variable VAR and redirect the output string to the COMMAND.

4.2. Basic Usage

The simplest form of here string comprised of a command, followed by a “<<<” redirector and a string:

cat <<< "This is a string"

Besides that, we can redirect a variable that contains a string:

WELCOME_MESSAGE="Welcome to dashboard"
cat <<< $WELCOME_MESSAGE

4.3. Here String With Parameter

Similar to a heredoc, we can also parameterize the output of our here string with variables:

cat <<< "Welcome! ${USER}"

4.4. Escape Special Characters in Here String

To escape special characters like $, \, and `, we can enclose the string with the single quote instead of the double quote:

cat <<< 'Display special characters: $ ` \'

If we enclose the here string with a single quote, variable expansion such as ${USER} will stop working.

5. Conclusion

In this article, we’ve introduced the syntax for heredoc and here string. Besides that, we’ve also briefly compared their differences in terms of functionality and syntax. Finally, we’ve also demonstrated several sample usages on both heredoc and here string.