# Here document

> Source: Courseiva IT Certification Glossary — https://courseiva.com/glossary/here-document

## Quick definition

A here document is a way to include a multiline block of text inside a script file. It lets you write commands or data exactly as you want them to appear, without worrying about quoting each line. Scripts use here documents to reduce clutter and make the code easier to read. Many IT exams expect you to recognize how here documents work in bash, PowerShell, or other shells.

## Simple meaning

Think of a here document as a prewritten note that you hand to a script so it can read the note line by line. In everyday life, if you had to give instructions to someone, you might write them all on one slip of paper. But if the instructions were long and included paragraphs, you would probably write them on a whole sheet of paper. That sheet of paper is like a here document: a chunk of text that the script takes in at once.

For example, imagine you are writing a recipe for a friend. Instead of telling them step 1, then step 2, then step 3 separately, you could hand them the entire recipe on one card. The script does the same with a here document: it reads the whole block of text between a start marker and an end marker. Inside that block, you can include variables such as the name of a user or a file path, and the script will automatically fill in the actual values.

Here documents are especially useful when you need to create configuration files, generate HTML content, or write code from within a script. Without here documents, you would have to use many echo commands and carefully manage quoting and escaping, which is tedious and error prone. The here document approach keeps everything neat and reduces mistakes.

In IT, you will often see here documents used in shell scripts, PowerShell scripts, and even in some programming languages like Perl or Ruby. They are a standard tool for automation tasks that involve generating dynamic content. Understanding them helps you write cleaner, more maintainable scripts, which is a skill tested in many IT certification exams.

## Technical definition

A here document, also known as a heredoc, is a multiline string literal that appears in source code and is treated as a block of input by the shell or scripting language interpreter. The standard syntax in bash or sh is: command << DELIMITER followed by the text block and ending with a line containing only the delimiter. For example, cat << EOF ... EOF sends the intermediate lines to the standard input of the cat command.

The delimiter can be any word, but common choices are EOF, END, or HEREDOC. The delimiter must appear on a line by itself, with no leading or trailing whitespace (unless quoting is used). There are two main variants: unquoted and quoted. In an unquoted here document, the shell expands environment variables and performs command substitution within the block. For example, if you write cat << EOF
Hello $USER
EOF, the output will include the current username. In a quoted variant, such as cat << 'EOF' or cat << \EOF, no expansion takes place, and the text is treated literally.

In PowerShell, the equivalent is a here-string. The syntax is @" ... "@ for an expanding here-string (variables are substituted) and @' ... '@ for a literal here-string. The start delimiter @" must be at the beginning of a line, and the end delimiter "@ must also be on its own line. PowerShell here-strings can span multiple lines and are commonly used for creating configuration files or embedding code.

Here documents are not limited to shell scripting. Many languages like Perl, Ruby, and Python (via triple-quoted strings) support similar constructs. In Perl, you write print <<EOF; and in Ruby, you write puts <<~EOF for a squiggly heredoc that strips leading whitespace.

From a protocol and standards perspective, there is no single formal standard, but the behavior is defined by the POSIX shell specification (IEEE Std 1003.1) for the shell command language. The specification details that the redirection operator << must be followed by a word that serves as the delimiter, and that the here-document input ends at the first line that contains only that delimiter.

In real IT implementations, here documents are used in automated deployment scripts, Dockerfile RUN commands, CI/CD pipeline scripts, and system administration tasks. They allow administrators to create files on the fly, such as configuration files for Apache, Nginx, or systemd, without needing separate file templates. This makes scripts self-contained and easier to version control.

A common exam trick involves heredoc delimiter quoting. If the delimiter is quoted, variables are not expanded. If it is unquoted, they are. Another trick is that leading tabs can be suppressed using <<- instead of <<, allowing the delimiter to be indented. The POSIX standard specifies this behavior, and it is often tested in the Linux+ or LPIC exams.

## Real-life example

Imagine you are planning a big family dinner and you need to give the grocery list to your partner. You could text them item by item: milk, eggs, bread, butter, and so on. But that is slow and easy to mess up. Instead, you write the entire list on a single piece of paper and hand it over. That piece of paper is a here document: a complete block of information that the receiver processes all at once.

Now suppose the list contains a placeholder like "Buy 2 bags of [partner's favorite snack]." If you were to write that on the paper, you would have to know the snack name in advance. But if you use a here document, you can leave a variable in the text, and the script fills it in automatically. It is like writing on the paper, "Buy 2 bags of $snack" and then telling the script that $snack stands for "chocolate chips." The script replaces the variable before showing the list.

In real life, we also have situations where the content must be taken literally. For example, if a recipe includes the instruction "Add $1 of sugar" and you do not want the dollar sign to be interpreted as a variable, you would put that line inside a quoted here document. This is similar to writing the recipe on a sticky note and then covering the sticky note with transparent tape so nothing gets changed.

Another everyday analogy: imagine you are composing an email but you want to include a block of text from a document. Instead of retyping the whole paragraph, you copy and paste it into the email body. The copy-paste buffer is like a here document: you capture a chunk of text and insert it exactly where you need it. The script reads that chunk without requiring you to format each line individually.

These analogies highlight the core idea: here documents provide a clean, efficient way to handle multiline content in scripts, just as a single sheet of paper is better than a stack of individual notes for a long list.

## Why it matters

Here documents matter in IT because they dramatically simplify script writing and maintenance. Without them, generating dynamic configuration files or sending multiline messages would require many echo or printf commands, each with careful escaping. A here document reduces the chance of syntax errors and makes the script more readable. When a script is easier to read, it is also easier to debug and share with team members.

In the context of automation, here documents are widely used in DevOps practices. For example, when provisioning a server with a script, you often need to create files like /etc/nginx/nginx.conf. Instead of using a separate file template that must be fetched from a repository, you can embed the configuration directly in the script using a here document. This makes the script self-contained and simplifies deployment.

From a security viewpoint, here documents can be used to avoid injection vulnerabilities if used correctly. Because the delimiter can be quoted, you can ensure that no variable expansion or command substitution occurs, which is important when the content includes user input or special characters. Incorrect use, however, can lead to unintended variable expansion, which might reveal sensitive information or break the script.

Understanding here documents is also important for exam preparation because many certification exams, such as CompTIA Linux+, LPIC-1, and RHCSA, include questions about redirection, heredocs, and quoting. They may ask you to identify the output of a script that uses a here document, or to choose the correct syntax for a given scenario. Knowing the difference between quoted and unquoted delimiters, and the <<- operator, can be the key to a correct answer.

here documents are not just a convenience; they are a fundamental tool in the scripting toolbox. They improve code quality, reduce errors, and are a recurring topic in IT exams. Mastery of here documents demonstrates a solid grasp of shell scripting and automation principles.

## Why it matters in exams

Here documents appear in several major IT certification exams, including CompTIA Linux+, LPIC-1, RHCSA, and even some Microsoft exams that cover PowerShell scripting. In these exams, you are expected to understand the syntax, behavior, and practical use cases of here documents. The objectives often list redirection and piping, but here documents are a specific form of input redirection that exam writers frequently test.

For CompTIA Linux+ (XK0-005), one of the exam objectives is to demonstrate knowledge of shell scripting, including input and output redirection. A typical question might present a script that uses a here document to create a configuration file and then ask for the resulting file content. Another question might ask you to identify why an unquoted delimiter caused variable expansion that led to an error.

In the LPIC-1 exam (101-500), the topic of shell scripting includes heredocs under the section on redirection and pipes. The exam might test your ability to write a here document that creates a multiline file without expanding variables. You may also be asked about the <<- operator, which strips leading tabs, allowing the delimiter to be indented. This is a common trick because learners often forget that the delimiter must be at the start of the line unless <<- is used.

For the Red Hat Certified System Administrator (RHCSA) exam, heredocs are frequently used in exam tasks that require creating files with specific content. For example, you might be told to create a script that writes a cron job configuration using a heredoc. The exam environment is command line based, so you must type the syntax exactly correct. A missing newline or an extra space before the delimiter can cause the heredoc to fail, which examiners know and use to differentiate careful candidates.

Even in non-Linux exams, like the Microsoft AZ-104 (Azure Administrator) or MS-102, PowerShell here-strings are used in scripts for automation. Candidates may need to understand how to create a here-string to pass JSON or XML data to a cmdlet. The concept is the same as in bash, but the syntax differs. The exam may present a scenario where a here-string improves script readability and ask for the correct implementation.

In multiple-choice questions, the pattern often involves evaluating the output of a script that uses a heredoc. For instance, you might see a script that defines a variable inside the heredoc and then echo that variable outside. Because the heredoc is a block of text, variables defined inside it are not available outside unless the script is structured differently. Recognizing this scope issue is a valuable exam skill.

Overall, here documents are a tested topic in many general IT certifications. They are not the most complex subject, but they are a common point of confusion. Mastery can earn you easy points on straightforward questions and help you avoid traps in more complex scenarios.

## How it appears in exam questions

Questions about here documents typically fall into a few patterns: output prediction, syntax correction, scenario application, and troubleshooting. In output prediction questions, you are given a short script that uses a here document and are asked what the script will display or what file content will be created. For example:

#!/bin/bash
name="Alice"
cat << END
Hello $name
Welcome to the system.
END

The answer is "Hello Alice" followed by "Welcome to the system." because the unquoted delimiter END allows variable expansion. If the delimiter were quoted, like << 'END', the output would be "Hello $name" literally.

Syntax correction questions present a snippet with a deliberate error, such as a missing line break before the delimiter, extra spaces before the delimiter, or using a reserved word as the delimiter. The candidate must identify the fix. For instance, if the delimiter appears with leading spaces, the shell will not recognize it as the termination marker. The correct fix is to ensure the delimiter is on its own line with no leading whitespace (unless <<- is used).

Scenario application questions ask you to choose the best approach to solve a task. For example, "You need to create an Nginx configuration file as part of a deployment script. Which method will ensure the file is created with the correct content and minimal risk of syntax errors?" The best answer is using a here document with a quoted delimiter to prevent variable expansion, because configuration files often contain dollar signs that should stay literal.

Troubleshooting questions describe a script that is not behaving as expected. For example, a script uses a heredoc to send an email, but the email contains literal $VARIABLE instead of the actual value. The issue is that the heredoc delimiter was quoted. The fix is to remove the quotes. Another example: a script fails because the delimiter line has trailing whitespace. The fix is to remove the spaces.

In PowerShell exams, the question might show a script using @" ... "@ and ask what variable substitution occurs. Or they might show a here-string that is meant to create a JSON file but fails because of incorrect closing delimiter. The candidate must know that the closing delimiter must be on its own line, with no other characters.

These question patterns test both recall and application. To answer them correctly, you need to know the syntax rules and the effects of quoting. You also need to understand practical implications, such as avoiding variable expansion in configuration files. Practice with sample questions that use heredocs will build the mental reflexes needed for exam day.

## Example scenario

You are a system administrator tasked with creating a script that generates a welcome message file for a new user. The welcome message should include the user's name, the current date, and a greeting. The script will create a file named welcome.txt in the user's home directory.

You decide to use a here document to keep the code clean. Here is the script:

#!/bin/bash
username="jdoe"
current_date=$(date +%Y-%m-%d)
cat > /home/$username/welcome.txt << EOF
Welcome, $username!

Your account was created on $current_date.
Here are some tips:
- Change your password immediately.
- Review the system usage policy.

Best regards,
Admin
EOF

When the script runs, the shell processes the here document. It sees the delimiter EOF unquoted, so it expands the variables $username and $current_date. The cat command receives the expanded text and writes it to /home/jdoe/welcome.txt. The resulting file contains:

Welcome, jdoe!

Your account was created on 2025-02-24.
Here are some tips:
- Change your password immediately.
- Review the system usage policy.

Best regards,
Admin

Now suppose the user's name contains a dollar sign, such as "r$dollar". If the delimiter is unquoted, the shell might try to expand $dollar as a variable. To avoid this, you would quote the delimiter: << 'EOF'. Then the file would include the literal string "$dollar" instead of trying to substitute it.

This scenario demonstrates a real-world use of here documents in user provisioning scripts. It is simple, effective, and avoids the need for multiple echo commands. The same technique is used in many other contexts, such as generating configuration files, sending email notifications, or creating temporary scripts that run during deployment.

## Common mistakes

- **Mistake:** Using a delimiter that appears inside the here document content
  - Why it is wrong: If the delimiter word appears on a line by itself within the text, the shell treats that line as the end of the here document, cutting the content short. For example, if you use EOF as the delimiter and your text contains a line with just EOF, your document will end prematurely.
  - Fix: Choose a delimiter that is unlikely to appear in the text. Common safe choices are HEREDOC, ENDMARKER, or a unique string like DELIM123. Avoid using single letters or common words.
- **Mistake:** Putting whitespace before the delimiter line
  - Why it is wrong: The delimiter must be the only thing on its line, with no leading or trailing whitespace (unless you use <<- which strips leading tabs). If you accidentally indent the delimiter line, the shell will not recognize it as the end of the here document, leading to a syntax error.
  - Fix: Use <<- if you want to indent the delimiter. In bash, <<- allows the delimiter to have leading tab characters. Otherwise, ensure the delimiter is flush left. In PowerShell, the closing delimiter must be at the beginning of the line with no spaces.
- **Mistake:** Forgetting to quote the delimiter when variable expansion is not desired
  - Why it is wrong: When you want to include literal text that contains dollar signs or backticks, an unquoted delimiter will cause the shell to expand them. This can corrupt configuration files or scripts that rely on those characters.
  - Fix: Use a quoted delimiter like << 'EOF' or << \EOF. In PowerShell, use @' ... '@ for literal here-strings. This prevents any expansion, ensuring the text is taken exactly as written.
- **Mistake:** Placing additional text on the same line as the delimiter
  - Why it is wrong: The line that marks the end of the here document must contain only the delimiter. If you add a comment or any other character after the delimiter, the shell will not recognize it as the end marker.
  - Fix: Always put the delimiter on a line by itself with no other text, not even whitespace. If you need to comment, place the comment before or after the heredoc block.
- **Mistake:** Confusing << with < or <<<
  - Why it is wrong: The here document uses double less-than signs (<<) followed by a delimiter. A single less-than (<) is for redirecting input from a file, and <<< is a here string used for a single line of input. Using the wrong operator can lead to unexpected behavior or errors.
  - Fix: Remember: << starts a here document, < reads from a file, and <<< sends a single string. Use << when you have multiple lines of text to include.

## Exam trap

{"trap":"In an exam question, a script uses << 'EOF' but the student expects variable expansion. The question asks for the output, and one of the answer choices shows the expanded version.","why_learners_choose_it":"Learners often memorize that heredocs allow variable expansion, but they forget that quoting the delimiter changes the behavior. They see a familiar pattern (heredoc with EOF) and assume expansion occurs, without noticing the single quotes around the delimiter.","how_to_avoid_it":"Always check whether the delimiter is quoted or unquoted. Look for quotes around the delimiter in the command line: << 'EOF' means literal, << EOF means expand. In PowerShell, check if it is @\" (expanding) or @' (literal). Train yourself to see that detail. On exam day, read the syntax carefully before jumping to conclusions."}

## Commonly confused with

- **Here document vs Here string (<<<):** A here string sends a single line of text as input to a command, while a here document can send multiple lines. Here strings use <<< followed by a string. For example, grep pattern <<< 'my string' is a here string. Here documents use << followed by a delimiter and can span many lines. (Example: cat <<< 'Hello World' shows the string, but cat << EOF
Hello World
EOF shows the same but across two lines.)
- **Here document vs Input redirection (<):** Input redirection with < reads the contents of a file as input to a command. A here document, on the other hand, reads input that is embedded directly in the script, not from a file. They are both forms of redirection, but here documents are self-contained within the script file. (Example: cat < /etc/hosts reads the hosts file. cat << EOF ... EOF reads text written inside the script.)
- **Here document vs Pipe (|):** A pipe sends the output of one command as input to another. A here document provides input data from within the script to a command. They are often used together (e.g., cat << EOF | grep something), but they serve different roles: pipe connects commands, heredoc supplies data. (Example: echo 'Hello' | grep H uses a pipe. cat << EOF | grep H uses a heredoc to supply the same data.)
- **Here document vs Command substitution ($()):** Command substitution runs a command and returns its output as a string. It can be used inside a here document (with unquoted delimiter) to insert dynamic content. However, command substitution itself is not a heredoc; it is a separate feature used to embed command results. (Example: cat << EOF
Today is $(date)
EOF uses command substitution inside a heredoc to show the current date.)

## Step-by-step breakdown

1. **Write the command that will receive the input** — Start with a command that accepts standard input, such as cat, grep, sed, or a redirect to a file (>> or >). This command will process the lines from the here document.
2. **Type the redirection operator and delimiter** — After the command, type << followed by a delimiter word. The delimiter can be any string, but it is typically a word like EOF, END, or HEREDOC. If you do not want variable expansion, enclose the delimiter in quotes: << 'EOF'.
3. **Press Enter and write the content lines** — On the next lines, enter the text you want to include. Each line becomes part of the input. Variables and command substitutions will be expanded if the delimiter is unquoted. If you need literal dollar signs, use a quoted delimiter.
4. **Terminate the here document with the delimiter** — On a new line, type the delimiter exactly as it was written in step 2, with no leading or trailing spaces. The line must contain only the delimiter. This signals the end of the input.
5. **Allow the command to execute** — Once the complete here document is typed, the script moves forward. The command receives the input as if it were read from a file. The output of the command is displayed or redirected based on any additional redirections in the line.
6. **Check for indentation issues if using <<-** — If you used <<- instead of <<, the delimiter can be indented with tabs. Also, leading tabs in the content lines are stripped. This is useful for indenting heredocs inside loops or conditional statements for better readability.

## Practical mini-lesson

When working with here documents in production scripts, there are several best practices to follow. First, always choose a delimiter that is descriptive and unlikely to appear in the content. For example, if you are generating an HTML file, use HTML_END instead of EOF. This reduces the chance of accidental early termination.

Second, pay attention to quoting as it determines whether variables and command substitutions are expanded. In many deployment scripts, you want to generate files with dynamic content, so an unquoted delimiter is appropriate. However, when the content includes dollar signs, backticks, or backslashes that must remain literal, use a quoted delimiter.

Third, consider using <<- for indented heredocs when your script has nested structures. This is especially useful in functions or loops. The leading tabs are removed from both the content and the delimiter, allowing you to indent the entire heredoc with the surrounding code. Note that only tabs are stripped, not spaces, so you must use actual tab characters.

Another practical aspect is combining heredocs with other redirections. For example, you can write: cat << EOF > /path/to/file.txt to redirect the output directly to a file. You can also pipe the output of a heredoc to another command: cat << EOF | grep pattern. This flexibility makes heredocs powerful for one-liner data processing.

What can go wrong? A common issue is forgetting that the delimiter must be on its own line. If you add a space before the delimiter, the shell will not recognize it and will keep waiting for the end marker, causing the script to hang or fail. Another issue is using a variable inside a quoted heredoc and expecting it to expand. That will not happen, which might surprise newcomers.

here documents are straightforward but have subtle rules. The best way to master them is to practice writing scripts that create files or process text using heredocs. Try writing a script that backs up a configuration file by copying its content into a heredoc, then compare it with the original. This exercise will reinforce the syntax and behavior.

## Memory tip

Remember: "Quotes make it quotes, no quotes makes it go" – if you quote the delimiter, the text is literal; if you don't, variables are substituted.

## FAQ

**Can I use a here document inside a loop?**

Yes, you can use a heredoc inside a loop. If you want to indent the heredoc for readability, use <<- and ensure the delimiter is indented with tabs. The content lines can also be indented with tabs, which will be stripped.

**What happens if I forget the closing delimiter?**

The shell will continue reading input from the script file or terminal, making it appear as if the script is hanging. In a script, it will cause a syntax error. Always ensure the closing delimiter is on its own line with no extra characters.

**Can I use a here document with commands other than cat?**

Absolutely. Any command that reads standard input can use a heredoc, including grep, sed, awk, read, and even commands like ftp or mysql. The heredoc provides the input stream.

**What is the difference between << and <<< in bash?**

<< starts a multiline here document, while <<< is a here string that sends a single line. For example, << 'EOF' starts a block, while <<< 'text' sends the string 'text' as input.

**How do I include a literal dollar sign in a here document?**

Use a quoted delimiter like << 'EOF'. This prevents variable expansion, so the dollar sign is treated as a regular character. Alternatively, you can escape the dollar sign with a backslash, but only if the delimiter is unquoted; however, that can be confusing, so quoting is preferred.

**Is there a limit to the size of a here document?**

In practice, heredoc size is limited by available memory, as the entire content is stored before being passed to the command. For extremely large blocks, consider writing to a temporary file instead. For typical scripts, size rarely is an issue.

## Summary

The here document is a versatile scriptwriting feature that allows you to embed multiline text directly in a script without clutter. It works by redirecting a block of text between a start and end delimiter to a command's standard input. The key nuance is whether the delimiter is quoted: quoted delimiters prevent variable and command substitution, while unquoted delimiters allow expansion. This distinction is crucial for creating scripts that either generate dynamic content or preserve literal text.

In IT certification exams, here documents appear in Linux, Unix, and PowerShell contexts. They test your understanding of syntax, quoting rules, and the <<- operator for indentation. Common mistakes include misplacing whitespace before the delimiter, using a delimiter that appears in the content, and misapplying quoting. Exam traps often revolve around the subtle difference between quoted and unquoted delimiters, so careful reading of the script is essential.

In real-world practice, here documents simplify the creation of configuration files, email bodies, and code templates. They make scripts more readable and reduce the risk of syntax errors. By mastering here documents, you gain a tool that improves both your automation efficiency and your exam performance. Remember the memory tip: "Quotes make it quotes, no quotes makes it go." This will help you recall the expansion behavior when you need it most.

---

Practice questions and the full interactive page: https://courseiva.com/glossary/here-document