How do you indicate a comment line in a shell script?

Note: I updated this answer based on comments and other answers, so comments prior to May 22nd 2020 may no longer apply. Also I noticed today that some IDE's like VS Code and PyCharm do not recognize a HEREDOC marker that contains spaces, whereas bash has no problem with it, so I'm updating this answer again.

Bash does not provide a builtin syntax for multi-line comment but there are hacks using existing bash syntax that "happen to work now".

Personally I think the simplest (ie least noisy, least weird, easiest to type, most explicit) is to use a quoted HEREDOC, but make it obvious what you are doing, and use the same HEREDOC marker everywhere:

<<'###BLOCK-COMMENT'
line 1
line 2

line 3
line 4
###BLOCK-COMMENT

Single-quoting the HEREDOC marker avoids some shell parsing side-effects, such as weird subsitutions that would cause crash or output, and even parsing of the marker itself. So the single-quotes give you more freedom on the open-close comment marker.

For example the following uses a triple hash which kind of suggests multi-line comment in bash. This would crash the script if the single quotes were absent. Even if you remove ###, the FOO{} would crash the script (or cause bad substitution to be printed if no set -e) if it weren't for the single quotes:

set -e

<<'###BLOCK-COMMENT'
something something ${FOO{}} something
more comment
###BLOCK-COMMENT

ls

You could of course just use

set -e

<<'###'
something something ${FOO{}} something
more comment
###

ls

but the intent of this is definitely less clear to a reader unfamiliar with this trickery.

Note my original answer used '### BLOCK COMMENT', which is fine if you use vanilla vi/vim but today I noticed that PyCharm and VS Code don't recognize the closing marker if it has spaces.

Nowadays any good editor allows you to press ctrl-/ or similar, to un/comment the selection. Everyone definitely understands this:

# something something ${FOO{}} something
# more comment
# yet another line of comment

although admittedly, this is not nearly as convenient as the block comment above if you want to re-fill your paragraphs.

There are surely other techniques, but there doesn't seem to be a "conventional" way to do it. It would be nice if ###> and ###< could be added to bash to indicate start and end of comment block, seems like it could be pretty straightforward.

Every programming language, including Bash, support a form of comments. As one of the key properties of a good shell script is to be reusable, it implies to be human-readable for anyone using the script, including yourself months later. Properly using bash comments ensure that your script can be maintained easily. Comments in Bash scripts are often overlooked and underappreciated, leading to hard to debug problems and hours of frustrations.

How to Comment Lines in a Bash Script?

Bash comments can only be done as single-line comment using the hash character #. Every line or word starting by the # sign cause all the following content to be ignored by the bash shell. This is the only way to do a bash comment and ensure text or code is absolutely not evaluated in Bash.

The only exception is the first line of a script with the shebang #! which is used to specify the script interpreter to be used on Linux and Unix platforms. This is still considered a comment in Bash and ignored by the Bash interpreter.

For multiple lines comments or block comments in Bash, see the Mistake #5 Using Unconventional Block Comments

#!/bin/bash
# This is a single-line comment in bash

echo "Hello World!" # This is an inline comment in bash

⚠️ In an interactive shell, when the option interactive_comments is disabled, the comments won’t be allowed. If you try to use comments in such a scenario you will get the following error bash: #: command not found. You can fix this by using

#!/bin/bash
# This is an example of a File Header comments in Bash
#
# Copyright 2020 John Doe
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see .

echo "Hello World!" # This is an inline comment in bash

0.

The 5 Mistakes To Avoid

1. Not Having a File Header Comment

This is part of programming 101 and it is also true when writing a script in Bash. All scripts must start with a comment that describes the purpose of the script. This is often called a File Header. Not having a file header prevent users to quickly understand and utilize your script without reading the full script. In some cases, it will also be the place where you will want to provide the authors’ names and include a copyright notice.

👉 Note, that including a proper copyright notice in each source file is a requirement under many open source licenses, including the GPL

.

#!/bin/bash
# This is an example of a File Header comments in Bash
#
# Copyright 2020 John Doe
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see .

echo "Hello World!" # This is an inline comment in bash

2. Missing Function Comments

Commenting functions is also a recommended programming practice. Generally, all bash functionsshould be commented. An exception can be made for small and obvious functions in a simple script. Libraries should always have their functions commented. Function comments in bash should state the following as necessary:

• Description of the function
• List of global variables used or modified
• Arguments taken by the function
• Outputs of the function to STDOUT and STDERR
• Returned values other than the exit status of the last command run

#######################################
# Print a given string
# GLOBALS:
#   A_STRING_PREFIX
# ARGUMENTS:
#   String to print
# OUTPUTS:
#   Write String to stdout
# RETURN:
#   0 if print succeeds, non-zero on error.
#######################################
function print_string() {
  echo "${A_STRING_PREFIX}: $1"
}

3. Making Long and Verbose Comments

You should comment on all the important and complex parts of your code, including non-obvious or know-how sections. Though, this doesn’t mean you should comment on everything. A simple echo line or a bash arithmetic additionis not warranted a long and verbose comment.

Don’t make your bash script longer and harder to work with by using overly long comments.

4. Not Using Consistent Labeling for TODO Comments

Every program, including your bash script, that is a work in progress should be open to future modification and improvement. When doing your first few iterations, you may find yourself adding comments for some

#!/bin/bash
# This is an example of a File Header comments in Bash
#
# Copyright 2020 John Doe
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see .

echo "Hello World!" # This is an inline comment in bash

#!/bin/bash
# This is an example of a File Header comments in Bash
#
# Copyright 2020 John Doe
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see .

echo "Hello World!" # This is an inline comment in bash

Your label can be whatever you want, TODO is the most obvious one being used. The important point is consistency across your code repository. Depending on your use case, you may also want to include the name and email address of the person making the comment who may be the subject matter expert to resolve or discuss this TODO task.

# TODO(John Doe, [email protected]): This is an example of TODO comment in bash (bug ####)

5. Using Unconventional Block Comments

Let’s be clear, there is no block comment in Bash. Block comments are often called multiple lines comments. Any alternative in Bash that mimics block comments is a convenience that can be error-prone. A common alternative is to use the heredoc notation with the bash null command. This is acceptable to do in some edge cases when debugging, troubleshooting, or while refactoring a large portion of code. Though, this shouldn’t be a standard way to comment in Bash.

One practical reason to stick to the hash mark # to comment in bash is that it allows a user to quickly grepthrough a script and get all the human-readable comments to understand the shell script.

If you want multiline comments in bash, and choose to use the heredoc notation with the bash null command, then make sure to single quote the heredoc delimiter otherwise variables will be expanded.

What symbols represent a comment in the Linux shell?

Which is the symbol used for comments in Bash shell scripting?

Which command is used for comment a line?

What does $? Mean in shell?