How to Use Heredoc in Shell Scripting

The Heredoc or Here Document is an input literal used by many programming and scripting languages. The Heredoc was originally used in UNIX Shells and is in fashion till date and, is supported by all popular Linux shells such as zsh, bash, tsh, etc. The symbol for a Heredoc is ‘<<‘ two left chevrons.

Syntax

<< 'Delimiter'
---statements/comments---
'Delimiter'

A Heredoc is followed by a delimiter token, which in turn is followed by a content block. The block ended with the same delimiter token. 
There are various delimiters that can be used such as BLOCK COMMENT, etc. In this article, we shall discuss some of the major and commonly used delimiter tokens.

Using Heredoc with SSH

Now, being a handy tool, the Heredoc can be used with SSH to execute multiple commands at the remote server. We shall see the same with an example.

ssh user@<server-ip-address> <<EOF
  "SSH connected user name: \$USER"
  "Current user name: $USER"
  EOF

Here the <server-ip-address> will take the IP address of the ssh-server and the user preceding the @ in the above code will be the username that needs to be accessed. The output produced will be:

In this example, we simply pass two commands to the SSH connection within a Heredoc block that displays the usernames of the client and server machines. This way, the Heredoc can be used to execute multiple commands in a single block. 
A thing to be noted here is that the SSH connection stays connected only as long as all the statements within the Heredoc are executed.

Executing commands with Heredoc

The block delimiter is followed by the << which, is followed by a shell command. This allows the user to execute multiple commands from a single block, or multiple statements with a single command. See the following example where we use the CAT shell command to print multiple input lines.

#!/bin/bash

cat << BLOCK
This is a block delimiter
Used with a CAT command.
BLOCK

The above shell script will display the two lines in the terminal. See the output below.

As can be seen, the heredoc.sh contains the above code example and on execution, it displays the contents of BLOCK delimiter-block as it would do for a single line.

Using the ‘-‘ with Heredoc – White/Tab space suppression

The Heredoc (<<) does not suppress additional tabs and whitespaces on default settings. We add a hyphen (-) after the Heredoc to suppress tabs but, no whitespaces. See the following example.

#!/bin/bash

cat <<- BLOCK
 This is block delimiter.
    This is a tabbed line.
BLOCK

The output will be:

As can be seen, the whitespace in the first line of the BLOCK is not suppressed however, the tab space in the second line is suppressed by the addition of the hyphen after the Heredoc.

The COMMENT delimiter

In Shell Scripting, comments are followed by the # literal. However, for multiline comments, adding the # as a suffix to each line is not an efficient way to create multiline comments. To do the same in a more programmatic way, we can use the Heredoc with COMMENT delimiter. See the following example to understand how.

#!/bin/bash

<< COMMENT
Multiline comment 1
Multiline comment 2
Multiline comment 3
COMMENT

echo "Comments added"

Output:

Now, in the above script, we added dummy comments followed by a print (echo) statement that displays the message that comments are added. The same is shown in the above output.

Use of variable in Heredoc text

We can perform variable substitution with Heredoc in bash. The variable usage is similar to a normal bash script, by using the ${} notation. See the following example.

#!/bin/bash

name=$1

cat << EOF
The name of the owner is ${name}
EOF

Here, we will take the name from the user during the script execution and then, display the same.

Output:

Escaping special characters

We can use the backslash (\) literal to escape special characters either in an entire block or a specific line in a block.
While escaping an entire block, we can do one of the following:

1. Prefix the delimiter with a backslash \.
2. Enclose the delimiter in single or double quotes.

See the following example.

#!/bin/bash

name=$1

cat << BLOCK
The name is ${name}
this line ha\$ \$pecial character\$.
BLOCK
echo
cat << \BLOCK2
The name is ${name}
this linr has special characters.
BLOCK2
echo
cat << 'BLOCK3'
The name is ${name}
this linr has special characters.
BLOCK3

Output:

In this example, we create three Heredoc blocks. The first block escapes individual special characters. The second block escapes all special characters with the backlash and the last block escapes all special characters with quotes. 
The same can be verified with the output provided above.

Create a new bash file with Heredoc

To create a new bash file with Heredoc, one should use the following syntax:

<<EOF > filename.sh
#!/bin/bash
EOF

The Heredoc will write the header lines to the newly created file and will add the bash header to it. In case a file with a similar name exists, this will overwrite it. See the below example.

Heredoc with functions

We can use Heredoc with functions to pass them multiple arguments to the function call. In the following example, we will create a function to take a person’s details and then, display the same.

#!/bin/bash

details(){
    read name
    read age
    read nat 
}

details << EOF
Harry
23
Brit 
EOF

echo 'Name is' $name
echo 'Age is' $age
echo 'Nationality is' $nat

Here, we create a function that reads three variables and later on passes those three variables from a Heredoc. 

Output:

Piping/Redirecting and Command substitution 

In this section, we shall understand how to use commands inside a Heredoc and how to pipe/redirect the output of a Heredoc to another command.

#!/bin/bash
cat <<EOF  | grep ssh
$(ps -A)
EOF

In the above code, the $() allows any shell command to be executed from within the Heredoc, and the cat << EOF | grep ssh pipes all the outputs of ps -A command to grep command, which then, sorts out the lines with keyword ‘ssh’. 

Output:

As it can be seen, the ps -A command fetches all the running processes however, when its output is redirected to grep, it in turn displays only those lines that contain the keyword ‘ssh’.

Conclusions

This article discussed how to use the Heredoc in Shell Scripting. We discussed some of the commonly used delimiters with the Heredoc. Then, we explored all other possibilities of using a Heredoc in a shell script with extensive examples.