HEREDOC (Here Documents) in Bash and Linux Shell – Tutorial

This article will show you how to use a Heredoc (Here Document) in Bash/Shell scripts to work with multi-line text.

Heredocs are most useful for accepting multi-line input- the user can enter a line of text, press enter, then enter the next line, and so on. It can also be used to define multi-line text in scripts.

It can also send multiple commands into an interactive program – this will be shown in the examples later.

The examples in this article will work in both Bash and Zsh Shells.

Standard Input, Piping, and Redirection

Heredoc is commonly used with Standard Input/Output and redirection/piping to send the multiline text to other commands for processing, formatting, or display. This topic really needs an article to itself to explain the concept, so here it is:

Redirect stdin, stdout, stderr in Linux/Bash, With Examples

The examples below will use the concepts and methods covered in the above article at several points.

Bash/Zsh Heredoc Syntax

To start a Heredoc, you simply use the << command. This is a form of Input/Output redirection outlined above.

The syntax for using a Heredoc is as follows:

COMMAND <<LIMITSTRING
text line 1
text line 2
...
LIMITSTRING

Note that:

• COMMAND can be any Linux command or script – the contents of the text contained in the heredoc will be sent to it using redirection
• << Defines the beginning of the Heredoc statement
  • If you are going to be indenting the multi-line text, use <<- (note the added dash) instead – it will strip leading tabs from each line
• LIMITSTRING is the string that must be typed to end the entering of text for the Heredoc
  • As Heredocs are multi-line, with the user pressing the ENTER key to move to the next line, you can’t press enter to stop entering new text.
  • LIMITSTRING, on its appearance, tells Heredoc that you’re done entering text and to finish up
  • It can be anything – make sure you use a series of characters that won’t be needing to appear in your text so that it isn’t ended prematurely.
  • A common practice is to use the text EOF (short for End Of File) as the LIMITSTRING – so long as this text isn’t going to be appearing inside the Heredoc.
• You can have as many lines of text as you like

Heredoc Examples

Accepting Multi-Line Text Input

This example will accept multiple lines of text and send them to the cat command for display:

cat <<EOF
This is line 1
This is line 2
EOF

The above example should be typed into your terminal program.

Using Variables

You can use shell variables in your Heredoc:

cat <<EOF
This is line 1
This is line 2
Your current directory is $PWD
EOF

Above, the $PWD variable is displayed in one of the lines of the Heredoc – this variable holds the value of the current working directory.

Redirecting the output of a Heredoc

Standard redirection (see earlier in the article if you don’t know what this is) can be used to send the contents of the Heredoc after it has been sent to the COMMAND to another program or file:

cat <<EOF > output.txt
This is line 1
This is line 2
Your current directory is $PWD
EOF

Above, cat reads the contents of the Heredoc, and the output of cat is redirected and written to the file output.txt using the > command.

Defining Multi-Line Text In Scripts

You can use a Heredoc in a script. As a shell script is just a list of line-by-line commands to be fed into the shell, it will behave the same way.

It’s nice to be able to indent your script code – if you don’t want those tabs to appear in your text, you can add a – (dash) to your Heredoc declaration to strip any white space from the beginning of each line:

#!/bin/bash

if $trueOrFalse; then
    cat <<-EOF > output.txt
    This is line 1
    This is line 2
    Your current directory is $PWD
    EOF
fi

#!/bin/bash

Assigning a Heredoc to a Variable

You can assign the multi-line text in a Heredoc to a script variable by reading it with the cat command and assigning the output to a variable like so:

mytext=$(cat <<-EOF 
    This is line 1
    This is line 2
    Your current directory is $PWD
    EOF
)

echo $mytext

Sending Multiple Commands to an Interactive Program

Heredocs can also send multiple lines of text to an interactive program. Some programs, once launched, expect you to type your own commands – they may accept text for processing or provide their own shell for issuing commands.

One example of this is MySQL – once MySQL has launched and connected to a server, you can type your own commands followed by the enter key to query data. By using a Heredoc, you can have these commands pre-written and send them into MySQL without user interaction:

mysql -uUSERNAME -pPASSWORD DATABASE <<EOF
SHOW TABLES;
SELECT * FROM posts;
EOF

Above, the MySQL command is used to connect to a given DATABASE with USERNAME and PASSWORD.

Two sequential commands will then be issued once the connection is ready – one to SHOW TABLES and one to SELECT all records from the posts table.