A Heredoc (Here document) is a redirection type which allows to pass multiline lines of input to a command. Sometimes while writing shell scripts you need to pass multiline block of code or text with the command like cat, sftp or tee. In this guide, you will learn how to use the Heredoc in bash.

Following is the basic syntax for the HereDoc:

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

Here,

• It starts with optional command followed by the redirection operator << and delimiter in first line.
  • The most commonly used delimiting identifiers are EOF or END. You can use any string for it.
  • If the delimiting identifier is unquoted, the shell will substitute all variables, commands and special characters before passing the here-document lines to the command.
  • Use the minus sign to the redirection operator <<- to ignore the all leading tab characters. It will maintain proper indentation.
• You can give variables, strings, command or any other type of input in the here-document block.
• The last line ends with the delimiting identifier. White space in front of the delimiter is not allowed.

Basic Heredoc Examples#

For better understanding let’s see few examples of heredoc. Mostly, heredoc is used in combination with the cat command.

Below, we are passing multiple lines which print the home directory path using an environment variable and cat command with here document:

cat << EOF
The home directory is: $HOME
You are logged in as: $(whoami)
EOF

You will get the following output:

The home directory is: /home/tecnstuff
You are logged in as: tecnstuff

In output both the variable and the command output are substituted.

Another example, in which we will enclose the delimiter in single or double quotes:

cat <<- "EOF"
The home directory is: $HOME
You are logged in as: $(whoami)
EOF

You will get he following output and you can see that when the delimiter is quoted, shell will not command substitution.

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

When you are using a heredoc inside a statement or loop, use the <<- redirection operation that allows you to indent your code.

if true; then
    cat <<- EOF
    Line with indent.
    EOF
fi

Line with indent.

You also can redirect the output to a file instead of displaying on a screen using the >, >> operators.

cat << EOF > output.txt
The home directory is: $HOME
You are logged in as: $(whoami)
EOF

If you will use the > operator, it will overwrite the file and >> will append the output to the file. If the given file output.txt doesn’t exist it will be created.

Using Heredoc with SSH#

On the remote system over SSH, you can run multiline command using the Heredoc easily.

Ensure that you have escape all commands, variables and special characters while using without quotes, otherwise they will be
execute locally:

ssh -T username@ip_or_hostname << EOF
echo "The local home directory is: $HOME"
echo "The remote home directory is: \$HOME"
EOF

The local home directory is: /home/tecnstuff
The remote home directory is: /home/username

Visit our guide to set up an SSH key-based authentication to connect your Linux servers without entering a password.

Conclusion#

You have learned basics of the heredoc and use it in your bash scripts.

If you have any questions or feedback, feel free to leave a comment.