[docs] Add a verbose explanation on how tox exec works

[webknjaz]

This docs section https://tox.wiki/en/latest/cli_interface.html#tox-exec-(e) does not actually show how to pass a command in (it's not in the signature). And it doesn't explain if the default commands are executed. It documents --notest in the signature, which makes it confusing — does the passed command replace the defined ones or does it augment them? What about commands_pre?

From what I saw in the wild (https://github.com/jamescooke/flake8-aaa/blob/master/Makefile#L42C2-L42C10), the command to execute should be passed after --. But that's a typical syntax for {posargs}. So how do these parts play together?

[webknjaz]

Alright… I played with it, and it seems that it replaces commands_pre, commands and commands_post.

Interestingly, passing --notest to tox makes it skip executing the command:

$ tox e -e pre-commit -qq -- python -c 'print("eh?")'
eh?

$ tox e -e pre-commit -qq --notest -- python -c 'print("eh?")'

[gaborbernat]

Yeah, no tests probably shouldn't be allowed to be called and otherwise just replaces the commands with something passed in from the CLI.

[ssbarnea]

In fact I ended up here discovering that exec fails if the command I try to run is not in the allowlist_externals,... which pretty much makes the exec feature unusable.

IMHO, exec should bypass the allowlist_externals checks. WDYT?

[jugmac00]

@gaborbernat What is your take on that?

[gaborbernat]

In fact I ended up here discovering that exec fails if the command I try to run is not in the allowlist_externals,... which pretty much makes the exec feature unusable.

IMHO, exec should bypass the allowlist_externals checks. WDYT?

Don't think so. The point of this is to be able to execute comments within the virtual environment without needing to activate the virtual environment. At most I can imagine the exec subcommand receiving some kind of flag that allows bypassing, but I would not want to have it as default.