539

I know how to write a multi-line command in a Bash script, but how can I add a comment for each line in a multiline command?

CommandName InputFiles      \ # This is the comment for the 1st line
            --option1 arg1  \ # This is the comment for the 2nd line
            --option2 arg2    # This is the comment for the 3nd line

But unfortunately, the comment after continuation character \ will break the command.

4
  • Copy the code block to a commented/annotated block adjacent to it, if you update the code just remember to update the comment block.
    – user4401178
    Commented Nov 12, 2015 at 15:52
  • note: this problem and its solutions also apply to multiline strings.
    – phil294
    Commented Sep 1, 2017 at 22:15
  • 3
    FYI this is not a duplicate of this question the linked question is asking about a command that uses pipes... vs this question is talking about one command that has many options. not the same thing. Commented Mar 1, 2018 at 20:28
  • Replace the space before the # comment symbol with a newline? You can alternate continuation lines with comment lines in a shell script file with no special tricks, it seems. Commented May 2, 2021 at 0:19

4 Answers 4

926

This is how I do it. Essentially by using Bash's backtick command substitution one can place these comments anywhere along a long command line even if it is split across lines. I have put the echo command in front of your example so that you can execute the example and see how it works:

echo CommandName InputFiles `#1st comment` \
             --option1 arg1 `#2nd comment` \
             --option2 arg2 `#3rd comment`

Another example where you can put multiple comments at different points on one line:

some_cmd --opt1 `#1st comment` --opt2 `#2nd comment` --opt3 `#3rd comment`
22
  • 10
    It even works within piped sub-commands: "echo `#1` foo \(newline) | perl -ne `#2` 'print'"... exactly what I needed! Commented Jan 29, 2013 at 23:49
  • 69
    This technique creates a subshell for each inline comment, so these are very expensive comments. They are only suitable on lines that are executed infrequently.
    – pjh
    Commented Dec 10, 2014 at 16:52
  • 80
    These comments are very expensive because each of them creates a subshell. That makes the technique unusable in some circumstances. A much cheaper, if less readable, alternative that uses the same basic idea is: echo CommandName InputFiles ${IFS# 1st comment} --option1 arg1 ${IFS# 2nd comment} --option2 arg2 ${IFS# 3rd comment}.
    – pjh
    Commented Dec 15, 2014 at 11:10
  • 17
    Interesting how it only works with backticks but not when using command substitution using $(). Is there any reason why?
    – phk
    Commented Sep 2, 2016 at 15:24
  • 14
    @phk "Interesting how it only works with backticks but not when using command substitution using $(). Is there any reason why?" Once $() sees the #, the rest of the line is treated as comments, and the parentheses never gets closed. Backticks parse differently. You can do $(: comment) instead. stackoverflow.com/questions/1455988/commenting-in-a-bash-script/…
    – wisbucky
    Commented Jul 10, 2019 at 22:46
170

You could store the arguments in an array:

args=(
    InputFiles           # This is the comment for the 1st line
    --option1 arg1       # This is the comment for the 2nd line
    --option2 arg2       # This is the comment for the 3nd line
    #--deprecated-option # Option disabled
)
CommandName "${args[@]}"

and you can even add blank lines to enhance readability:

args=(

    # This is the comment for the 1st line
    InputFiles

    # This is the comment for the 2nd line
    --option1 arg1

    # This is the comment for the 3nd line
    --option2 arg2

    # Option disabled
    #--deprecated-option

)
CommandName "${args[@]}"

If you need to use other shell operators, such as booleans and pipes, you cannot place them inside the array(s) but you can "glue" them together when you execute:

args1=(
    InputFiles           # This is the comment for the 1st line
    --option1 arg1       # This is the comment for the 2nd line
    --option2 arg2       # This is the comment for the 3nd line
    #--deprecated-option # Option disabled
)
args2=(
    --option arg         # Another comment
    example.config
)
success=(
    # Put the command in the array if it is clearer
    notify-send
    Hooray
    'The thing is done'
)
fail=(
    notify-send
    'Uh oh'
    "The thing didn't work"
)
CommandName1 "${args1[@]}" | CommandName2 "${args2[@]}" 2>> error.log && "${success[@]}" || "${fail[@]}"
6
  • @Philipp Hmmm, thanks. It's a good workaround. but I'm afraid it will be a little bit confusing if my --option arg has both ' and ".
    – Peter Lee
    Commented Mar 1, 2012 at 19:58
  • @Philipp, I really don't which one should be the correct answer. It seems there is no correct answer. So I upvoted your answer, and marked Perry's as the correct answer.
    – Peter Lee
    Commented Mar 5, 2012 at 17:15
  • 2
    @PeterLee: you can use " and ' in arrays as well.
    – Philipp
    Commented Mar 5, 2012 at 22:16
  • 10
    Less hackish is to just store the arguments in the array, then use them like so: CommandName "${args[@]}".
    – chepner
    Commented Dec 10, 2014 at 14:17
  • 4
    This format is superior to all the others if you wish to be able to comment out entire lines in an argument list. command "${args[@]}" ftw. Commented Jan 2, 2015 at 11:50
116

I'm afraid that, in general, you can't do what you're asking for. The best you can do is a comment on the lines before the command, or one single comment at the end of the command line, or a comment after the command.

You can't manage to intersperse comments inside a command this way. The \s express an intent to merge lines, so for all intents and purposes you're trying to intersperse comments in a single line, which doesn't work anyway because a \ has to be at the end of the line to have that effect.

8
  • 10
    Not to mention that "The \ s effectively merge those lines" isn't even right, the problem is that the backslash must immediately precede the newline in order to escape it, whereas with cmd \ # comment there's whitespace and a comment in between the backslash and the newline. Commented Feb 24, 2017 at 23:20
  • 18
    Accepted answer should be Marwan's below. Commented Jul 16, 2017 at 21:27
  • 5
    I think I disagree, Marwan's answer is clever but feels like an abuse of substitution. If anything I'd say Philipp's answer is closer to something I'd want to do.
    – alecbz
    Commented Sep 20, 2017 at 18:27
  • 2
    The fact that this one is marked as the accepted answer while Marwan's answer is recommended against on grounds which are irrelevant for 99% (performance) / 100% ("feels wrong") of users coming here looking for solutions is both sad and representative of what's wrong with software development.
    – misberner
    Commented Nov 17, 2018 at 21:04
  • 1
    Just because a kludge is popular doesn't make it a good idea at all.
    – Perry
    Commented Nov 4, 2021 at 15:43
21

Based on pjh's comment to another answer to this question, replacing IFS with a variable known to contain no non-whitespace characters.

comment=
who ${comment# This is the command} \
    -u ${comment# This is the argument}

Why aren't the parameter expansions quoted? The variable is initialized with an empty string. When the parameter expansion occurs, the # operator (unrelated to the shell comment character #, but used for the similarity) attempts to strip the actual comment from the parameter value. The result, of course, is still an empty string.

An unquoted parameter expansion undergoes word-splitting and pathname generation. In this case, neither process creates any additional words from an empty string, so the result is still an empty string. Such an empty string is simply discarded without affecting the command in which it appears. The above is precisely equivalent to

who \
  -u
6
  • This too is problematic because it relies on not using double-quotes around the expansion, so that it disappears with word-splitting. That goes in counter to how it's far more often necessary to teach people to add the double-quotes, so that word-splitting doesn't mess them up the moment that a whitespace character appears in the data.
    – ilkkachu
    Commented Feb 17, 2021 at 16:55
  • 2
    I think it's important to understand why quoting is almost always important, as well as understanding why a lack of quoting could be intentional.
    – chepner
    Commented Feb 17, 2021 at 17:06
  • 1
    (That said, this is a gross hack that I would never actually use it in my own shell scripts.)
    – chepner
    Commented Feb 17, 2021 at 17:13
  • 2
    If you want to be 100% sure that comment is an empty variable, declare it as readonly comment=. This will even prevent functions to redefine a local comment.
    – Socowi
    Commented Aug 24, 2021 at 10:20
  • 4
    For ${parameter#word} POSIX specifies "word shall be subjected to tilde expansion, parameter expansion, command substitution, and arithmetic expansion" and somewhat vaguely "If word is not needed, it shall not be expanded". If $parameter is empty, bash does not expand word but still parses it. Therefore, the comments need correct shell syntax, even though they are not executed. Example: echo ${comment# 12" (inch) are 1' (foot)} results in unexpected EOF while looking for matching `"'.
    – Socowi
    Commented Aug 24, 2021 at 11:50

Not the answer you're looking for? Browse other questions tagged or ask your own question.