In Bash and other shells like Zsh, a Here document (Heredoc) is a type of redirection that allows you to pass multiple lines of input to a command.
The syntax of writing HereDoc takes the following form:
[COMMAND] <<[-] 'DELIMITER' HERE-DOCUMENT DELIMITER
- The first line starts with an optional command followed by the special redirection operator
<<and the delimiting identifier.
- You can use any string as a delimiting identifier, the most commonly used are EOF or END.
- 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.
- Appending a minus sign to the redirection operator
<<-, will cause all leading tab characters to be ignored. This allows you to use indentation when writing here-documents in shell scripts. Leading whitespace characters are not allowed, only tab.
- The here-document block can contain strings, variables, commands and any other type of input.
- The last line ends with the delimiting identifier. White space in front of the delimiter is not allowed.
Basic Heredoc Examples
In this section, we will look at some basic examples of how to use heredoc.
Heredoc is most often used in combination with the cat command.
In the following example, we are passing two lines of text containing an environment variable and a command to
cat using a here document.
cat << EOF The current working directory is: $PWD You are logged in as: $(whoami) EOF
As you can see from the output below, both the variable and the command output are substituted:
The current working directory is: /home/black You are logged in as: black
Let’s see what will happen if we enclose the delimiter in single or double quotes.
cat <<- "EOF" The current working directory is: $PWD You are logged in as: $(whoami) EOF
You can notice that when the delimiter is quoted no parameter expansion and command substitution is done by the shell.
The current working directory is: $PWD You are logged in as: $(whoami)
If 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 a leading tab. EOF fi
Line with a leading tab.
Instead of displaying the output on the screen you can redirect it to a file using the
cat << EOF > file.txt The current working directory is: $PWD You are logged in as: $(whoami) EOF
If the file.txt doesn’t exist it will be created. When using
> the file will be overwritten, while the
>> will append the output to the file.
The heredoc input can also be piped. In the following example the
sed command will replace all instances of the
l character with
cat <<'EOF' | sed 's/l/e/g' Hello World EOF
To write the piped data to a file:
cat <<'EOF' | sed 's/l/e/g' > file.txt Hello World EOF
Using Heredoc with SSH
Using Heredoc is one of the most convenient and easiest ways to execute multiple commands on a remote system over SSH.
When using unquoted delimiter make sure you escape all variables, commands and special characters otherwise they will be interpolated locally:
ssh -T email@example.com << EOF echo "The current local working directory is: $PWD" echo "The current remote working directory is: \$PWD" EOF
The current local working directory is: /home/black The current remote working directory is: /home/user
You may also want to set up an SSH key-based authentication and connect to your Linux servers without entering a password.
In this guide, you have learned what is
heredoc and how to use it in your shell scripts.
If you have any questions or feedback, feel free to leave a comment.