Bash Heredoc

Introduction

Before we begin talking about bash heredoc, let's briefly understand – What is HereDoc?

Bash has a handy tool called "heredoc," which is short for "here document," that lets you add multiline or huge text blocks right in your script. It removes the requirement for numerous echo statements or external files in order to accept text input. Heredoc is particularly helpful when producing documentation, embedding complex strings, and supplying input for operations that need multiple lines of input.

When building shell scripts, you might find yourself needing to provide a multiline block of text or code to an interactive command like tee, cat, or sftp.

A Here document (Heredoc) is a sort of redirection in Bash and other shells like Zsh that allows you to provide numerous lines of input to a command.

In this tutorial, you will understand Bash heredoc. We will also address a few FAQs on Bash heredoc.

HereDoc Syntax

The following is the syntax for writing HereDoc:

[COMMAND] <<[-] 'DELIMITER'
  HERE-DOCUMENT
DELIMITER

The optional command is followed by the special redirection operator << and the delimiting identifier on the first line.
As a delimiting identifier, you can use any string; the most frequent ones are EOF and END.
The shell will substitute all variables, commands, and special characters before forwarding the here-document lines to the command if the delimiting identifier is not quoted.
All leading tab characters will be ignored if you add a minus sign to the redirection operator -. This allows you to use indentation in shell scripts while writing here-documents. Only tab is allowed in front of whitespace characters.
Strings, variables, commands, and any other type of input can be placed in the here-document block.
The delimiting identifier is at the end of the last line. There must be no white space in front of the delimiter.

Basic Heredoc Examples

We'll look at some simple examples of how to use heredoc in this section.

The cat command is frequently used in conjunction with Heredoc.

Using a here document, we provide two lines of text to the cat, one holding an environment variable and the other a command.

cat << EOF
The current working directory is: $PWD
You are logged in as: $(whoami)
EOF

Both the variable and the command output are substituted, as shown in the output below:

The current working directory is: /home/vegastack
You are logged in as: vegastack

Let's check what happens if we use single or double quotes to enclose the delimiter.

cat <<- "EOF"
The current working directory is: $PWD
You are logged in as: $(whoami)
EOF

When the delimiter is quoted, the shell does not do any parameter expansion or command substitution.

Output

The current working directory is: $PWD
You are logged in as: $(whoami)

If you want to indent your code while using a heredoc inside a statement or loop, use the <<- redirection operation.

if true; then
    cat <<- EOF
    Line with a leading tab.
EOF
fi

Output

Line with a leading tab.

Using the > and >> operators, you can divert the output to a file instead of displaying it on the screen.

cat << EOF > file.txt
The current working directory is: $PWD
You are logged in as: $(whoami)
EOF

The file.txt will be generated if it does not already exist. The file will be overwritten if you use >, whereas >> will append the output to the file.

The heredoc input can be piped as well. The sed command will replace all instances of the l letter with e in the following example:

cat <<'EOF' |  sed 's/l/e/g'
Hello
World
EOF

Output

Heeeo
Wored

To write the piped data to a file, follow these steps:

cat <<'EOF' |  sed 's/l/e/g' > file.txt
Hello
World
EOF

Using Heredoc with SSH

One of the most handy and straightforward ways to run several commands on a remote system over SSH is to use Heredoc.

If you use an unquoted delimiter, you must escape any variables, commands, and special characters, or they will be interpolated locally:

ssh -T [email protected] << EOF
echo "The current local working directory is: $PWD"
echo "The current remote working directory is: \$PWD"
EOF

Output

The current local working directory is: /home/linuxize
The current remote working directory is: /home/user

Set up SSH key-based authentication to log in to your Linux servers without having to enter a password.

FAQs on Bash HereDoc

How do I use Heredoc in Bash?

To use Heredoc, you begin with the << operator followed by a unique delimiter. After the delimiter, you can include your multiline text. Finally, end the Heredoc block with the same delimiter.

What is the purpose of the delimiter in a Heredoc block?

The delimiter in a Heredoc block serves as a marker that defines the start and end of the included multiline text. It can be any unique string as long as it does not appear in the text.

Can I use variables and special characters within a Heredoc block?

Yes, you can use variables and special characters within a Heredoc block. Bash will interpret variables and expand them, just like in double-quoted strings.

What happens with leading tabs or spaces in a Heredoc block?

Leading tabs or spaces, known as leading whitespace, are preserved in a Heredoc block. If you want to remove leading whitespace, you can use the <<- operator instead of <<.

Can I use command substitution within a Heredoc block?

Yes, you can use command substitution within a Heredoc block by enclosing the command substitution with $(). Bash will execute the command and substitute its output within the Heredoc block.

Can I redirect the output of a Heredoc block to a file?

Yes, you can redirect the output of a Heredoc block to a file by using the > or >> redirection operator followed by the filename. For example, command << EOF > output.txt.

Can I define multiple Heredoc blocks within a script?

Yes, you can define multiple Heredoc blocks within a script using different delimiter strings. Each Heredoc block will be treated separately and can contain distinct multiline text.