I get slighty confused with • shell_command • run_shell_command • adhoc_tool is there any documentation that explains the difference between these three ? They clearly have a nice overlap of features & reasons.

indeed they do, and I totally agree (and would also benefit from) a write up on this topic. from what I understand,

shell_command

allows you to run any executable you may find on your system, in a sandbox along with any target dependencies, as part of another pants goal. The

run_shell_command

does the same, but as a stand alone pants goal, and runs in your workspace and any target dependencies are placed to the side in a

"{chroot}"

you can reference to get at them.

adhoc_tool

then is, I think, an evolution of

shell_command

where you can leverage any runnable pants target as the command to execute, and also have more (better) support for optionally capturing stdout/stderr as proper outputs for downstream targets to consume. I have only vague familiarity with

adhoc_tool

as I've not really used it at all (yet), where as I wrote the initial implementation for the shell command variants in their experimental version before graduating.

@ancient-vegetable-10556 is the expert on all this.

Just from my experience

shell_command

, as Andreas explained, runs in a sandbox but is not a directly runnable target (i.e. you can't

pants run :my_shell_command

). That's where

run_shell_command

comes in, as you can run it via

pants run ...

, but it runs in your project root instead of a sandbox.

adhoc_tool

combines a bit of both, but I like to think of it as a cacheable command where you need some output effect to run your next command. Think of it like running

npm install

to refresh your

node_modules

before running a runnable target like

npm run-script serve

. All of this is IMHO, as I'm not an expert in its entirety.

That's interesting- so - generating semver/conventional co mit versions via an external tool - (convco) would need to be either executed as run_shell_command or adhoc_tool as it needs to read the git commits. And generate (bespoke use case goal) the VERSION files. Shell_command can't work because in the sandbox the .git repo is not there. As it would read git history / caching can't work either as the logical compute key is the reflog :-). But adhoc let's you depend upon its output 1. Currently it's run via a Run_shell_command which writes the version/change log files. 2. Adhoc may produce the same.outcome