499

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
    Nov 12, 2015 at 15:52
  • note: this problem and its solutions also apply to multiline strings.
    – phil294
    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. 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. May 2, 2021 at 0:19

4 Answers 4

886

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`
21
  • 10
    It even works within piped sub-commands: "echo `#1` foo \(newline) | perl -ne `#2` 'print'"... exactly what I needed! Jan 29, 2013 at 23:49
  • 64
    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
    Dec 10, 2014 at 16:52
  • 75
    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
    Dec 15, 2014 at 11:10
  • 15
    Interesting how it only works with backticks but not when using command substitution using $(). Is there any reason why?
    – phk
    Sep 2, 2016 at 15:24
  • 11
    @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
    Jul 10, 2019 at 22:46
156

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[@]}"
7
  • 10
    That works for something simple like the OP's example, but it won't support > and < and | and || and && and so on.
    – ruakh
    Mar 1, 2012 at 19:48
  • @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
    Mar 1, 2012 at 19:58
  • 2
    @PeterLee: you can use " and ' in arrays as well.
    – Philipp
    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
    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. Jan 2, 2015 at 11:50
111

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. Feb 24, 2017 at 23:20
  • 16
    Accepted answer should be Marwan's below. 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
    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
    Nov 17, 2018 at 21:04
  • 1
    Just because a kludge is popular doesn't make it a good idea at all.
    – Perry
    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
    Feb 17, 2021 at 16:55
  • 1
    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
    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
    Feb 17, 2021 at 17:13
  • 1
    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
    Aug 24, 2021 at 10:20
  • 2
    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
    Aug 24, 2021 at 11:50

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