Multi-Line Comment Using : ' ... ' in Bash

---

Learning Focus

1. Understand how the syntax : ' ... ' works in Bash.
2. Learn why it effectively behaves as a multi-line comment.
3. Apply this technique for long documentation or disabled code blocks.
4. Recognize its differences from heredoc-style comments.
5. Avoid syntax mistakes that cause execution errors.

---

2. 5W + 1H Framework

Element	Description
What	: ' ... ' uses the null command (:) with a quoted string to ignore a block of text.
Why	To include long explanations, notes, or temporarily disabled code within Bash scripts without execution.
Who	Script authors, VPS administrators, and WordPress automation engineers documenting large scripts.
When	During development, debugging, or internal documentation.
Where	Anywhere inside a Bash script or interactive shell.
How	Begin with : followed by a single quote ', then your comment block, and close with another '.

---

3. Core Syntax & Concept

Syntax Formula

: '
multi-line comment text
goes here
and can span
several lines
'

Behavior

• : is a Bash built-in that does nothing (returns exit status 0).
• The quoted string is treated as an argument to :.
• The interpreter reads but does not execute the text inside quotes.
• Result: The entire quoted block is effectively ignored.

---

Example 1 — Basic Multi-Line Comment

#!/bin/bash

: '
This script automates WordPress maintenance tasks:
1. Performs site backup
2. Updates plugins
3. Flushes cache
4. Sends completion report
'

echo "Running maintenance..."

Expected Output:

Running maintenance...

Explanation: Everything inside the quoted block is ignored because it is just a literal string passed to :, which does nothing.

Example 2 — Temporary Disable Code

#!/bin/bash

: '
wp plugin update --all --allow-root --path=/home/site/public_html
wp cache flush --allow-root --path=/home/site/public_html
'

echo "Skipped plugin updates for testing."

Expected Output:

Skipped plugin updates for testing.

Explanation: The WP-CLI commands inside the block are not executed. Useful when debugging or testing parts of a script.

Example 3 — Use Inside Loops

for s in /home/*/*/public_html; do
: '
echo "→ Updating: $s"
wp plugin update --all --allow-root --path="$s"
'
echo "Checked folder: $s"
done

Expected Output:

Checked folder: /home/.../public_html
Checked folder: /home/.../public_html

Explanation: All commands within : ' ... ' are skipped; only the last echo executes.

4. Implementation Steps

1. Open your script file:

nano /root/wp-maintenance.sh

2. Insert a descriptive comment block:

: '
=============================================
WordPress Maintenance Script
- Backups database
- Updates plugins
- Purges cache
=============================================
'

3. Continue with active commands below:

echo "→ Running maintenance process..."

4. Save and run:

chmod +x /root/wp-maintenance.sh
./root/wp-maintenance.sh

---

5. Best Practices

Tip	Description
Always close the quote properly	Both opening and closing ' must exist.
Avoid nested single quotes inside the block	They break string syntax.
Use only single quotes (') — not double quotes (")	Prevent variable or command expansion.
Keep the block outside of active pipelines or heredocs	To prevent misinterpretation.
Combine with # for shorter notes	Use # for one-line; : ' ... ' for long sections.

---

6. Troubleshooting Matrix

Problem	Cause	Solution
unexpected EOF	Missing closing '	Add matching quote at the end of block
Text executes accidentally	Used : without quotes	Ensure you wrap comment block in ' '
Variable expands in comment	Used double quotes	Use single quotes ' to disable expansion
Syntax error in loop	Misaligned indentation	Align start and end quotes on new lines

---

7. Quick Lab

Objective: Add and remove a : ' ... ' block in a WordPress automation script.

#!/bin/bash

: '
This block documents the purpose of the script.
Currently, we are disabling plugin update commands
for safety during maintenance testing.
'

for c in /home/*/*/public_html/wp-config.php; do
site=$(dirname "$c")
echo "→ Checking: $site"
# : ' wp plugin update --all --allow-root --path="$site" '
done

Expected Output:

→ Checking: /home/.../public_html
→ Checking: /home/.../public_html

Explanation: The long text block is ignored, making it ideal for structured documentation.

8. Cheat Sheet

Method	Syntax	Purpose
Multi-Line Comment	: ' ... '	Ignore multi-line text
One-Line Comment	# text	Ignore single line
Disable Commands	: ' command block '	Skip code temporarily

---

9. Glossary

Term	Definition
Null Command (:)	Built-in command that does nothing, but always returns success.
Quoted String	Text wrapped in ' ' passed as argument to :.
Block Comment Simulation	Technique to ignore several lines at once using : ' ... '.

---

10. Mini-Quiz

1. What is the role of : in : ' ... '?
2. Why should you use single quotes instead of double quotes?
3. What happens if the closing ' is missing?
4. Can commands inside : ' ... ' execute?
5. How does this differ from # comments?

---

Would you like me to continue next with **comparison between : ' ... ' vs **: <<'EOF' ... EOF as a dedicated topic? It shows when to use each for documentation vs code disabling.

📘