What is the $BASH_COMMAND variable good for?
According to the Bash manual, the environment variable BASH_COMMAND contains
The command currently being executed or about to be executed, unless the shell is executing a command as the result of a trap, in which case it is the command executing at the time of the trap.
Taking that trap corner case aside, if I understand correctly this means that when I execute a command, the variable BASH_COMMAND contains that command. It's not absolutely clear whether that variable is unset after the command execution (i.e., is only avaialble while the command is running, but not after), though one might argue that since it is "the command currently being executed or about to be executed", it is not the command that was just executed.
But let's check:
$ set | grep BASH_COMMAND=
$
Empty. I would have expected to see BASH_COMMAND='set | grep BASH_COMMAND=' or maybe just BASH_COMMAND='set', but empty surprised me.
Let's try something else:
$ echo $BASH_COMMAND
echo $BASH_COMMAND
$
Well that makes sense. I execute the command echo $BASH_COMMAND and so the variable BASH_COMMAND contains the string echo $BASH_COMMAND. Why did it work this time, but not before?
Let's do the set thing again:
$ set | grep BASH_COMMAND=
BASH_COMMAND='echo $BASH_COMMAND'
$
So wait. It was set when I executed that echo command, and it was not unset afterwards. But when I executed set again, BASH_COMMAND was not set to the set command. No matter how often I execute the set command here, the result stays the same. So, is the variable set when executing echo, but not when executing set? Let's see.
$ echo Hello AskUbuntu
Hello AskUbuntu
$ set | grep BASH_COMMAND=
BASH_COMMAND='echo $BASH_COMMAND'
$
What? So the variable was set when I executed echo $BASH_COMMAND, but not when I executed echo Hello AskUbuntu? Where's the difference now? Is the variable only set when the current command itself actually forces the shell to evaluate the variable? Let's try something different. Maybe some external command this time, not a bash builtin, for a change.
$ /bin/echo $BASH_COMMAND
/bin/echo $BASH_COMMAND
$ set | grep BASH_COMMAND=
BASH_COMMAND='/bin/echo $BASH_COMMAND'
$
Hmm, ok... again, the variable was set. So is my current guess correct? Is the variable only set when it has to be evaluated? Why? Why? For performance reasons? Let's do one more try. We'll try to grep for $BASH_COMMAND in a file, and since $BASH_COMMAND should then contain a grep command, grep should grep for that grep command (i.e., for itself). so let's make an appropriate file:
$ echo -e "1 foo\n2 grep\n3 bar\n4 grep \$BASH_COMMAND tmp" > tmp
$ grep $BASH_COMMAND tmp
grep: $BASH_COMMAND: No such file or directory
tmp:2 grep <-- here, the word "grep" is RED
tmp:4 grep $BASH_COMMAND tmp <-- here, the word "grep" is RED
tmp:2 grep <-- here, the word "grep" is RED
tmp:4 grep $BASH_COMMAND tmp <-- here, the word "grep" is RED
$ set | grep BASH_COMMAND=
BASH_COMMAND='grep --color=auto $BASH_COMMAND tmp'
$
Ok, interesting. The command grep $BASH_COMMAND tmp got expanded to grep grep $BASH_COMMAND tmp tmp (the variable gets expanded just that once, of course), and so I grepped for grep, once in a file $BASH_COMMAND which doesn't exist, and twice in the file tmp.
Q1: Is my current assumption correct that:
-
BASH_COMMANDis only set when a command tries to actually evaluate it; and - it is not unset after execution of a command, even though the description may lead us to believe so?
Q2: If yes, why? Performance? If no, how else can the behavior in the above command sequence be explained?
Q3: Lastly, is there any scenario in which this variable could actually be meaningfully used? I was actually trying to use it within $PROMPT_COMMAND to analyze the command being executed (and do some stuff depending on that), but I can't, because as soon as, within my $PROMPT_COMMAND, I execute a command to look at the variable $BASH_COMMAND, the variable gets sets to that command. Even when I do MYVARIABLE=$BASH_COMMAND right at the beginning of my $PROMPT_COMMAND, then MYVARIABLE contains the string MYVARIABLE=$BASH_COMMAND, because an assignment is a command too. (This question is not about how I could obtain the current command within a $PROMPT_COMMAND execution. There are other ways, I know.)
It's a bit like with Heisenberg's uncertainty principle. Just by observing the variable, I change it.
Answering to the third question: of course it can be used meaningfully in the way at Bash manual clearly hints – in a trap, e. g.:
$ trap 'echo ‘$BASH_COMMAND’ failed with error code $?' ERR
$ fgfdjsa
fgfdjsa: command not found
‘fgfdjsa’ failed with error code 127
$ cat /etc/fgfdjsa
cat: /etc/fgfdjsa: No such file or directory
‘cat /etc/fgfdjsa’ failed with error code 1
Now that Q3 has been answered (correctly, in my opinion: BASH_COMMAND is useful in traps and hardly anywhere else), let's give Q1 and Q2 a shot.
The answer to Q1 is: the correctness of your assumption is undecidable. The truth of neither of the bullet points can be established, as they ask about unspecified behaviour. By its specification, the value of BASH_COMMAND is set to the text of a command for the duration of the execution of that command. The spec does not state what its value must be in any other situation, i.e. when no command is being executed. It could have any value or none at all.
The answer to Q2 "If no, how else can the behavior in the above command sequence be explained?" then follows logically (if somewhat pedantically): it is explained by the fact that the value of BASH_COMMAND is undefined. Since its value is undefined, it can have any value, which is exactly what the sequence shows.
Postscript
There is one point where I think you're indeed hitting a soft spot in the spec. It's where you say:
Even when I do MYVARIABLE=$BASH_COMMAND right at the beginning of my $PROMPT_COMMAND, then MYVARIABLE contains the string MYVARIABLE=$BASH_COMMAND, because an assignment is a command too.
The way I read the bash man page, the bit in italics is not true. The section SIMPLE COMMAND EXPANSION explains how first the variable assignments on the command line are set aside, and then
If no command name results [in other words, there were only variable assignments], the variable assignments affect the current shell environment.
This suggests to me that variable assignments are not commands (and therefore exempt from showing up in BASH_COMMAND), like in other programming languages. This would then also explain why there isn't a line BASH_COMMAND=set in the output of set, set essentially being a syntactic 'marker' for variable assignment.
OTOH, in the final paragraph of that section it says
If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits.
... which suggests otherwise, and variable assignments are commands too.
An inventive use for $BASH_COMMAND
Recently found this impressive use of $BASH_COMMAND in implementing a macro-like functionality.
This is the core trick of the alias and replaces the use of the DEBUG trap. If you read the part in the previous post about the DEBUG trap, you’ll recognize the $BASH_COMMAND variable. In that post I said that it was set to the text of the command before each call to the DEBUG trap. Well, it turns out it’s set before the execution of every command, DEBUG trap or no (e.g. run ‘echo “this command = $BASH_COMMAND”‘ to see what I’m talking about). By assigning it a variable (just for that line) we capture BASH_COMMAND at the outermost scope of the command, which will contain the entire command.
The author's previous article also provides some good background while implementing a technique using a DEBUG trap. The trap is eliminated in the improved version.