diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb index e10196c373..73a71a29e8 100644 --- a/Library/Homebrew/tap.rb +++ b/Library/Homebrew/tap.rb @@ -321,7 +321,7 @@ class Tap elsif (core_tap? || core_cask_tap?) && !Homebrew::EnvConfig.no_install_from_api? && !force # odeprecated: move to odie in the next minor release. This may break some CI so we should give notice. opoo "Tapping #{name} is no longer typically necessary.\n" \ - "Add #{Formatter.option("--force")} if you are sure you need one." + "Add #{Formatter.option("--force")} if you are sure you need it done." end clear_cache diff --git a/README.md b/README.md index 4fb5b138bf..9edf889204 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ We'd love you to contribute to Homebrew. First, please read our [Contribution Gu We explicitly welcome contributions from people who have never contributed to open-source before: we were all beginners once! We can help build on a partially working pull request with the aim of getting it merged. We are also actively seeking to diversify our contributors and especially welcome contributions from women from all backgrounds and people of colour. -A good starting point for contributing is running `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one. +A good starting point for contributing is to first [tap Homebrew/homebrew-core](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself), run `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one. Alternatively, for something more substantial, check out one of the issues labeled `help wanted` in [Homebrew/brew](https://github.com/homebrew/brew/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index 4525f7b592..2feb72559c 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -14,7 +14,7 @@ If everything checks out, you're ready to get started on a new formula! ### Writing the formula -1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled. +1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled. Start by tapping `homebrew/core`: first set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment, then run `brew tap homebrew/core` to clone the `homebrew/core` tap to the path returned by `brew --repository homebrew/core`. 1. If you're starting from scratch, you can use the [`brew create` command](Manpage.md#create-options-url) to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`. diff --git a/docs/FAQ.md b/docs/FAQ.md index c76562874f..a7c21433e8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -140,7 +140,13 @@ If all maintainer feedback has been addressed and all tests are passing, bump it ## Can I edit formulae myself? -Yes! It’s easy! If `brew tap` doesn't show `homebrew/core`, run `brew tap homebrew/core` first. Then just `brew edit `. You don’t have to submit modifications back to `homebrew/core`, just edit the formula to what you personally need and `brew install `. As a bonus, `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications! +Yes! It’s easy! If `brew tap` doesn't show `homebrew/core`, set yourself up to edit a local copy: + +1. Set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment, +2. Run `brew tap homebrew/core` and wait for the clone to complete, then +3. Run `brew edit ` to open the formula in `EDITOR`. + +You don’t have to submit modifications back to `homebrew/core`, just edit the formula to what you personally need and `brew install `. As a bonus, `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications! Note that if you are editing a core formula or cask you must set `HOMEBREW_NO_INSTALL_FROM_API=1` before using `brew install` or `brew update` otherwise they will ignore your local changes and default to the API. @@ -148,7 +154,7 @@ To undo all changes you have made to any of Homebrew's repositories, run `brew u ## Can I make new formulae? -Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in `EDITOR` so you can edit it, but it probably already installs; try it: `brew install `. If you encounter any issues, run the command with the `--debug` switch like so: `brew install --debug `, which drops you into a debugging shell. +Yes! It’s easy! If you already have a local copy of `homebrew/core` (see above), just use the [`brew create` command](Manpage.md#create-options-url). Homebrew will then open the formula in `EDITOR` so you can edit it, but it probably already installs; try it: `brew install `. If you encounter any issues, run the command with the `--debug` switch like so: `brew install --debug `, which drops you into a debugging shell. If you want your new formula to be part of `homebrew/core` or want to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md). diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index da2013f0d7..d9e11589ed 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -23,7 +23,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre Homebrew uses Git for storing formulae and contributing to the project. -As-of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded from JSON in which is automatically regenerated by a scheduled formulae.brew.sh job from the `master` branch of the homebrew-core repository. +As of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded as JSON from which is automatically regenerated by a scheduled [Homebrew/formulae.brew.sh](https://github.com/Homebrew/formulae.brew.sh) job from the `master` branch of the `homebrew/core` repository. Homebrew installs formulae to the Cellar at `$(brew --cellar)` and then symlinks some of the installation into the prefix at `$(brew --prefix)` (e.g. `/opt/homebrew`) so that other programs can see what's going on. We suggest running `brew ls` on a few of the kegs in your Cellar to see how it is all arranged. @@ -33,7 +33,7 @@ Packages are installed according to their formulae. Read over a simple one, e.g. Make sure you run `brew update` before you start. This ensures your Homebrew installation is a Git repository. -To create or edit formulae locally, you'll need to `brew tap homebrew/core` if you haven't previously. This taps homebrew-core, creating a Git repository in `$(brew --repository homebrew/core)`. As you are developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` before any `install`, `reinstall` or `upgrade` commands, to force `brew` to use the local repository instead of the API. +To create or edit formulae locally, you'll need to `brew tap --force homebrew/core` if you haven't previously. This clones the `homebrew/core` Git repository to `$(brew --repository homebrew/core)`. As you are developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` before any `install`, `reinstall` or `upgrade` commands, to force `brew` to use the local repository instead of the API. Before submitting a new formula make sure your package: diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md index 68cb597fa0..ea19eac591 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request.md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -36,7 +36,7 @@ The type of change you want to make influences which of Homebrew's main reposito 1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork). * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. -2. Download a local clone ("tap") the repository of core Homebrew formulae: +2. Tap (download a local clone of) the repository of core Homebrew formulae: ```sh brew tap --force homebrew/core @@ -60,7 +60,7 @@ The type of change you want to make influences which of Homebrew's main reposito 1. [Fork the Homebrew/homebrew-cask repository on GitHub](https://github.com/Homebrew/homebrew-cask/fork). * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories. -2. Download a local clone ("tap") the repository of core Homebrew casks: +2. Tap (download a local clone of) the repository of core Homebrew casks: ```sh brew tap --force homebrew/cask @@ -108,7 +108,7 @@ To make changes on a new branch and submit it for review, create a GitHub pull r ```sh brew tests - brew install --build-from-source + HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source brew test brew audit --strict --online ``` diff --git a/docs/Installation.md b/docs/Installation.md index fb417c3106..a0e8c69b64 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -36,7 +36,7 @@ export HOMEBREW_NO_INSTALL_FROM_API=1 This will make Homebrew install formulae and casks from the `homebrew/core` and `homebrew/cask` taps using local checkouts of these repositories instead of Homebrew’s API. -Note, this will take effect in supported configurations (i.e. using the default Homebrew prefix and, if on macOS, on a supported version). +Note that this will automatically be set on unsupported configurations (i.e. not using the default Homebrew prefix or, if on macOS, on an unsupported version). ## Unattended installation