add brew install --local flag

[0xdevalias]

Opening this as an issue as it sounds like a good idea, and as best I could tell from a quick search, I don't think it has been done yet/discussed further.

My personal interest in it is probably more focused on casks than formulae, so --build-from-source doesn't seem relevant to that use case.

Proposal

May want to consider making an explicit --build-from-source always bypass the API CC @Bo98 for thoughts.

I would rather lean more towards a new flag, e.g. --local or whatever, that is much more explicit that the intention is to use a locally edited formula. There's a question however of how should it behave for dependencies. Should those be installed from API or from the local clone? The latter is perhaps useful in some cases, though does mean that the flag would behave differently than how all other brew install flags work.

Originally posted by @Bo98 in Homebrew/homebrew-core#138060 (comment)

I would rather lean more towards a new flag, e.g. --local or whatever, that is much more explicit that the intention is to use a locally edited formula.

Great idea 👍🏻

There's a question however of how should it behave for dependencies. Should those be installed from API or from the local clone?

Hmm, good question. Feels like probably always using the local clone is better for consistency and because it's needed some of the time?

Originally posted by @MikeMcQuaid in Homebrew/homebrew-core#138060 (comment)

Workaround / Alternatives

I'm not sure if this is the canonical way, but as a workaround, currently when creating a new formula I just use a direct path to the file; eg.

brew install --cask $(brew --repository homebrew/cask)/Casks/f/foo.rb

This works ok, but is a little annoying/verbose in having to use the full path, or switch to the Casks directory first. It also seems to not play nice with the autocompletions, so I can't just tab my way to completing the filename/path.

• https://github.com/Homebrew/brew/tree/master/completions
  • https://github.com/Homebrew/brew/blob/master/completions/zsh/_brew#L1084-L1140

---

If the --local isn't a good option, then perhaps drawing attention to HOMEBREW_NO_INSTALL_FROM_API=1 (if that's the canonical way) in the text for brew install -h would be useful.

It was added to the pull request template for homebrew-core in:

• docs: add HOMEBREW_NO_INSTALL_FROM_API=1 note when building from source homebrew-core#138060

And there are already other env vars described in the brew install -h text:

brew/Library/Homebrew/cmd/install.rb

Lines 19 to 31 in de22479

	description <<~EOS
	Install a <formula> or <cask>. Additional options specific to a <formula> may be
	appended to the command.
	Unless `HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK` is set, `brew upgrade` or `brew reinstall` will be run for
	outdated dependents and dependents with broken linkage, respectively.
	Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for
	the installed formulae or, every 30 days, for all formulae.
	Unless `HOMEBREW_NO_INSTALL_UPGRADE` is set, `brew install` <formula> will upgrade <formula> if it
	is already installed but outdated.
	EOS

[Bo98]

I'd like to discourage HOMEBREW_NO_INSTALL_FROM_API=1 so I'm still hoping to do this, yeah.

I've been thinking about the dependency question a bit since, including common scenarios where users would run with --local. Using the API for dependencies is an easier/smaller change and potentially more like CI when you don't modify those dependencies (as CI will use those from master as it tests the merge commit). Using the local clone for all dependencies is slightly more code but does better cover the case when you are modifying mulitple formula in the same PR (if you are only installing the deepest dependent and not individually installing each), and is also more like how the current HOMEBREW_NO_INSTALL_FROM_API=1 recommendation behaves. Pros & cons for both in some ways - I'll draft out the implementation and make a decision.

[MikeMcQuaid]

Agreed this is a desirable feature, thanks for opening @0xdevalias.

@Bo98 I feel like --local should, ideally, just use the named formula from the tap and dependencies from the API (maybe unless they are changed in git but that probably starts to get overly complex).

[0xdevalias]

should, ideally, just use the named formula from the tap and dependencies from the API

Maybe --local could do this part; which would handle a majority of needs/cases in the simplest way.

(maybe unless they are changed in git but that probably starts to get overly complex).

And then some other flag used with it (--local-with-deps) could imply this part; for those more nuanced situations where multiple deps are being changed at once.

I also wouldn't be opposed to this only happening if they were changed as well, as 99.9% of the time I'm not going to have local differences unless I'm specifically working on them.

As for how to detect that easily/cleanly/with minimal code.. shrugs

[MikeMcQuaid]

should, ideally, just use the named formula from the tap and dependencies from the API

Maybe --local could do this part; which would handle a majority of needs/cases in the simplest way.

Agreed 👍🏻

[Bo98]

After reflecting on this overnight, making it behave like --build-from-source seems like it makes the most sense (so only the named formulae).

So yeah I agree with what was said here.

[0xdevalias]

If --local will have the same effect/semantics as --build-from-source; does that make them somewhat duplicates?

I like --build-from-source as it's very semantic/obvious, but it doesn't make sense for casks.

I like --local for it's simplicity.

Perhaps something could be added to --build-from-source that says it implies --local or similar to remove ambiguity?

Similar to how the docs for brew audit --new say that it implies --strict and --online

[Bo98]

I didn't mean a literal alias. I was talking more in terms of how things like --build-from-source don't build dependencies from source - only the formula you selected - and that's the type of behaviour I'd like here too.

But it will still behave similarly yes. For formulae, --local will basically be a scoped no-API load and then it will imply --build-from-source to the internal installer. Casks will just be the initial no-API load and that's it as the installer doesn't need to do anything differently beyond that.

[0xdevalias]

For formulae, --local will basically be a scoped no-API load and then it will imply --build-from-source to the internal installer.

That's the part that I think should be explicitly mentioned in the --help docs (similar to what build install --new does); so that people know that there is no reason to pass --local --build-from-source for example.

It's also somewhat confusing sometimes to know what flags are meant only for formula, which are for casks, and which apply to all. It would be nice if the help docs reflected that (though that's OOS of this issue) (Edit: see #16334)