Bash HereDoc Tutorial With Examples

March 3, 2022

Introduction

A here document (HereDoc) is a section of code that acts as a separate file. A HereDoc is a multiline string or a file literal for sending input streams to other commands and programs.

HereDocs are especially useful when redirecting multiple commands at once, which helps make Bash scripts neater and easier to understand.

This article teaches you the basics of using HereDoc notation and some typical use cases.

Bash HereDoc Tutorial With Examples

Prerequisites

Bash HereDoc Syntax

The syntax for writing a HereDoc is:

[COMMAND] <<[-] 'DELIMITER'
  Line 1
  Line 2
  ...
DELIMITER

It consists of the following elements:

  • COMMAND is optional. Works for any command that accepts redirection.
  • << is the redirection operator for forwarding a HereDoc to the COMMAND.
  • - is a parameter for tab suppression.
  • DELIMITER in the first line defines a HereDoc delimiter token. END, EOT, and EOF are most common, but any multicharacter word that won't appear in the body works. Omit single quotes on the first line to allow command and variable expansion.
  • The DELIMITER in the last line indicates the end of a HereDoc. Use the same word from the first line without the leading whitespaces.

The HereDoc itself contains any number of lines with strings, variables, commands, and other inputs.

Bash HereDoc Examples

This section showcases how to use the HereDoc notation in various situations. The most common use case is with the cat command.

Multiline String

Open the terminal and enter the following text, pressing Enter after each line:

cat << EOF
Hello
World
EOF
cat multiline heredoc

The cat command reads the HereDoc and writes the contents to the terminal.

Variable Expansion

A HereDoc accepts the use of variables and reads them.

To see how this works, create two variables in the terminal:

var1="Hello"
var2="World"

Pass the HereDoc to a cat command to print the two variables along with an environment variable:

cat << END
$var1
$var2
$PWD
END
heredoc variables

All the variables expand, and their respective values print to the terminal.

Command Expansion

HereDocs accept command substitution. Run the following code in the terminal line by line to see the results:

cat << EOF
$(echo Hello)
$(whoami)
EOF
cat command expansion

Encompass each command in $() to evaluate a statement and fetch the results. Omitting $() treats the text as a string.

Ignore Variable and Command Expansion

Add single or double quotes to the first delimiter to ignore variable and command expansion in a HereDoc.

For example:

cat << "EOF"
$(echo Hello)
$(whoami)
$PWD
EOF
heredoc quotation marks no expansion

Adding quotes to the delimiter treats the contents as a HereDoc literal.

Piping and Redirecting

Use piping or redirecting to forward the command results to another command. For example, create a Bash script and add the following contents to pipe a command:

#!/bin/bash

cat << EOF | base64 -d
SGVsbG8KV29ybGQK
EOF

Alternatively, use redirect notation to achieve the same result:

#!/bin/bash

(base64 -d) < cat << EOF
SGVsbG8KV29ybGQK
EOF

Run the Bash script to see the results.

redirecting heredoc

In both cases, the output from the cat and a HereDoc command pipes (or redirects) to the base64 -d command. As a result, the script decodes the message from the HereDoc.

Write to File

HereDoc allows writing multiline documents through one command.

To create a file and save the HereDoc contents, use the following format:

cat << EOF > hello_world.txt
Hello
World
EOF

If the document does not exist, the command creates it. Check the file contents to confirm:

cat hello_world.txt
heredoc to file

The console shows the file contents.

Note: Learn different methods on how to write to file in Bash.

Tab Suppression

Add a dash (-) after redirection to suppress leading tabs. For example, create and run the following script:

#!/bin/bash

cat <<- EOF
        Hello
        World
EOF
tab suppression heredoc

Without tab suppression, the message prints to the console with indentation. Adding the dash removes the tab indent and outputs the message without the leading spaces.

Note: If the text shows up with the leading spaces, press TAB instead of copying and pasting the example code.

Inside Statements and Loops

When working with a HereDoc inside statements and loops, keep in mind the following behavior:

  • Code inside statements and loops is indented. Add a dash after the redirect operator to print messages from a HereDoc without indentation.
  • The ending delimiter cannot have spaces or indentations before it.

Try the following example code to see how to use a HereDoc inside an if statement:

#!/bin/bash

if true;
then
        cat <<- "END"
        Hello
        World
END
fi
heredoc and if statement

The dash ensures the indents don't show up when the program runs. The ending delimiter is not indented, and adding spaces causes an error.

Multiline Comments

A HereDoc with the null command (:) creates the effect of block comments in Bash scripts.

For example:

#!/bin/bash

: << 'END'
This is a comment
END

Using HereDoc notation as a block comment is unconventional. In general, Bash does not support block commenting.

Escape Characters

To avoid character interpretation, add a backslash (\) before a character:

cat << EOF
\$100
EOF

Alternatively, avoid character interpretation completely by escaping the delimiter:

cat << \EOF
$100
EOF

Using quotation marks on the delimiter is equivalent in this case.

Functions

Add parameters to a function by forwarding information through a HereDoc. For example, create a function to read lines and add information through the HereDoc:

#!/bin/bash

readLines(){
        read greeting
        read name
}

readLines << EOF
Hello
$USER
EOF

echo $greeting
echo $name

The function stores the information provided by the HereDoc into variables.

heredoc and functions

Run the script to print the variable values to the terminal.

HereDoc and SSH

A HereDoc is convenient for executing multiple commands on a remote machine. Pass a HereDoc to the SSH connection to run multiple commands.

For example:

ssh username@host << EOF
echo "Local user: $USER"
echo "Remote user: \$USER"
EOF
ssh heredoc user local and remote

The command prints the local and remote users to the console.

HereDoc and SFTP

SFTP helps transfer data securely via the SSH protocol. Forward a HereDoc to run multiple SFTP commands automatically:

sftp username@host << EOF
put test.sh
EOF
sftp heredoc put

The code uploads a sample file to the remote machine.

Note: Learn how to read files line by line in Bash using here strings.

Conclusion

After going through the examples in this guide, you know how to use HereDoc notation in various situations. HereDoc helps pass multiple commands at once as input for different commands.

Next, learn about advanced text processing with the AWK command.

Was this article helpful?
YesNo
Milica Dancuk
Milica Dancuk is a technical writer at phoenixNAP with a passion for programming. With a background in Electrical Engineering and Computing, coupled with her teaching experience, she excels at simplifying complex technical concepts in her writing.
Next you should read
Bash printf - How to Print a Variable in Bash
February 24, 2022

The printf command produces formatted text outputs in the terminal. This tutorial shows how to use the printf command to print and format...
Read more
How to Write a Bash Script with Examples
December 23, 2021

Bash scripting is a key skill for both system administrators and developers. Learn how to write a Bash through a...
Read more
How to Comment in Bash
November 30, 2021

Comments are an essential part of programming. Learn how to use comments and the best practices to apply to your Bash script commenting techniques.
Read more
How To Check If File or Directory Exists in Bash
November 29, 2023

Searching for specific files or directories can be time-consuming. You can use a bash command or script to streamline the process...
Read more