Should HOMEBREW_INSTALL_FROM_API prevent installation of formula with "--HEAD" option?

[Cueball]

Been redoing my shell startup and general dotfiles; moved from rbenv to asdf in the process.

Attempted to install asdf with --HEAD:

brew install --HEAD asdf
Error: No head is defined for asdf

which it definitely is [asdf.rb:7].

Some digging pointed me towards HOMEBREW_INSTALL_FROM_API which admittedly I turned on without much investigation because "ooh new shiny and good feature‼1!" [not wrong, but I still didn't do any due diligence.]

Trying the asdf HEAD install with HOMEBREW_INSTALL_FROM_API unset seems to work fine:

❯ HOMEBREW_INSTALL_FROM_API= brew install --HEAD asdf
==> Cloning https://github.com/asdf-vm/asdf.git
Updating /Users/cueball/Library/Caches/Homebrew/asdf--git
==> Checking out branch master
Already on 'master'
Your branch is up to date with 'origin/master'.
HEAD is now at 24d524c chore: bump vuepress to latest beta (#1370)
==> Caveats
To use asdf, add the following line to your ~/.zshrc:
  . /usr/local/opt/asdf/libexec/asdf.sh

Restart your terminal for the settings to take effect.

zsh completions have been installed to:
  /usr/local/share/zsh/site-functions
==> Summary
🍺  /usr/local/Cellar/asdf/HEAD-24d524c: 166 files, 678.3KB, built in 10 seconds

From looking at Homebrew/brew#13439 it seems as though installing from source, and thus via --HEAD should probably not be allowed with HOMEBREW_INSTALL_FROM_API, but in all the other searching I've done, I can't find evidence or documentation of this.

If I can't install the occasional formula from --HEAD without losing the benefits of API install or jumping through hoops unsetting env vars, I'm going to need to reconsider some workflows...

Q: Should installing from HEAD be prevented with HOMEBREW_INSTALL_FROM_API enabled?

[SMillerDev]

As far as I know build from source is not supported through the api since the api only knows bottles.

Cc @Rylan12 for info and maybe improving the error

[Rylan12]

build from source is not supported through the api

Yes, this is correct. I'd be happy to look at a PR adding more documentation about this somewhere.