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
- 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
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
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.
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.