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.
- Access to the command line/terminal as a sudo user.
- A text editor to write Bash scripts.
- Basic Linux commands. For a quick reference, grab our Linux commands cheat sheet.
Bash HereDoc Syntax
The syntax for writing a HereDoc is:
[COMMAND] <<[-] 'DELIMITER'
It consists of the following elements:
COMMANDis optional. Works for any command that accepts redirection.
<<is the redirection operator for forwarding a HereDoc to the
-is a parameter for tab suppression.
DELIMITERin the first line defines a HereDoc delimiter token.
EOFare 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.
DELIMITERin 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.
Open the terminal and enter the following text, pressing Enter after each line:
cat << EOF
cat command reads the HereDoc and writes the contents to the terminal.
A HereDoc accepts the use of variables and reads them.
To see how this works, create two variables in the terminal:
Pass the HereDoc to a
cat command to print the two variables along with an environment variable:
cat << END
All the variables expand, and their respective values print to the terminal.
HereDocs accept command substitution. Run the following code in the terminal line by line to see the results:
cat << EOF
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.
cat << "EOF"
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:
cat << EOF | base64 -d
Alternatively, use redirect notation to achieve the same result:
(base64 -d) < cat << EOF
Run the Bash script to see the results.
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
If the document does not exist, the command creates it. Check the file contents to confirm:
The console shows the file contents.
Note: Learn different methods on how to write to file in Bash.
Add a dash (
-) after redirection to suppress leading tabs. For example, create and run the following script:
cat <<- EOF
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:
cat <<- "END"
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.
A HereDoc with the null command (
:) creates the effect of block comments in Bash scripts.
: << 'END'
This is a comment
Using HereDoc notation as a block comment is unconventional. In general, Bash does not support block commenting.
To avoid character interpretation, add a backslash (
\) before a character:
cat << EOF
Alternatively, avoid character interpretation completely by escaping the delimiter:
cat << \EOF
Using quotation marks on the delimiter is equivalent in this case.
readLines << EOF
The function stores the information provided by the HereDoc into variables.
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.
ssh username@host << EOF
echo "Local user: $USER"
echo "Remote user: \$USER"
The command prints the local and remote users to the console.
HereDoc and SFTP
sftp username@host << EOF
The code uploads a sample file to the remote machine.
Note: Learn how to read files line by line in Bash using
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.