I've seen it mentioned several times to fix issues with some packages, that it installs newer versions of packages somehow. But I've been unable to find a clear explanation of what that option really does, when to use it, why some packages have a --HEAD version to install and why its necessary.
I found some information in the Homebrew docs.
Quoting from under the "Advanced Formula Tricks" section:
Unstable versions (
Formulae can specify alternate downloads for the upstream project’s
develrelease (unstable but not
trunk) or HEAD (
HEAD URLs (activated by passing
--HEAD) build the development cutting edge.
Hopefully this helps with the what. I can't help with the why.
In git using the
--HEAD will grab all of the latest commits from the source repo. The problem with this is sometimes the latest revision will be in an inconsistant or unbuildable state, so use at your own risk.
When you sync from other tags that are published as "known stable" releases then the developer is saying that the files as they existed at that point will build and has passed all if its tests.
Running from head can be risky.