From 62a3b5e43e7356078fd7383d0c7d0021cf78e528 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Fri, 5 Sep 2025 17:42:34 +0100 Subject: [PATCH 1/2] How-to-Create-and-Maintain-a-Tap: improve docs. We don't really tell people actually how to create a tap here so let's provide more commands and output to help them. While we're here, also fix some bad references to `repo` that weren't updated when they should have been and let VSCode autoformat the Markdown. --- docs/How-to-Create-and-Maintain-a-Tap.md | 42 +++++++++++++++++++++--- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index a06a508ced..f43917edeb 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -1,5 +1,5 @@ --- -last_review_date: "1970-01-01" +last_review_date: "2025-09-05" --- # How to Create and Maintain a Tap @@ -10,23 +10,57 @@ last_review_date: "1970-01-01" A tap is usually a Git repository available online, but you can use anything as long as it’s a protocol that Git understands, or even just a directory with files in it. If hosted on GitHub, we recommend that the repository’s name start with `homebrew-` so the short `brew tap` command can be used. See the [`brew` manual page](Manpage.md) for more information on repository naming. -The `brew tap-new` command can be used to create a new tap along with some template files. +The `brew tap-new` command can be used to create a new tap along with some template files: + +```console +$ brew tap-new $YOUR_GITHUB_USERNAME/homebrew-tap +Initialized empty Git repository in /opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap/.git/ +... +==> Created $YOUR_GITHUB_USERNAME/tap +/opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap +``` + +Next, you can push it to a new GitHub repository: + +```console +$ gh repo create $YOUR_GITHUB_USERNAME/homebrew-tap --push --public --source "$(brew --repository $YOUR_GITHUB_USERNAME/homebrew-tap)" +✓ Created repository $YOUR_GITHUB_USERNAME/homebrew-tap on github.com + https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap +✓ Added remote https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap.git +... +✓ Pushed commits to https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap.git +``` Tap formulae follow the same format as the core’s ones, and can be added under either the `Formula` subdirectory, the `HomebrewFormula` subdirectory or the repository’s root. The first available directory is used, other locations will be ignored. We recommend the use of subdirectories because it makes the repository organisation easier to grasp, and top-level files are not mixed with formulae. See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of a tap with a `Formula` subdirectory. +### Creating your formula or cask + +Run `brew create` to create a formula or cask file in your tap and open it in your text editor: + +```console +$ brew create https://mirror.ibcp.fr/pub/gnu/wget/wget-1.25.0.tar.gz --tap $YOUR_GITHUB_USERNAME/homebrew-tap --set-name $YOUR_GITHUB_USERNAME-wget +==> Downloading from https://mirror.ibcp.fr/pub/gnu/wget/wget-1.25.0.tar.gz +... +Editing /opt/homebrew/Library/Taps/$YOUR_GITHUB_USERNAME/homebrew-tap/Formula/$YOUR_GITHUB_USERNAME-wget.rb +``` + +After that, follow the [Adding Software to Homebrew](Adding-Software-to-Homebrew.md) guide to create your formula or cask file. + +Finally, `git add`, `git commit` and `git push` your formula or cask to your tap and others can use it too. + ### Naming your formulae to avoid clashes If a formula in your tap has the same name as a Homebrew/homebrew-core formula they cannot be installed side-by-side. If you wish to create a different version of a formula that's in Homebrew/homebrew-core (e.g. with `option`s) consider giving it a different name; e.g. `nginx-full` for a more full-featured `nginx` formula. This will allow both `nginx` and `nginx-full` to be installed at the same time (assuming one is [keg-only](FAQ.md#what-does-keg-only-mean) or the linked files do not clash). ## Installing -If it’s on GitHub, users can install any of your formulae with `brew install user/repo/formula`. Homebrew will automatically add your `github.com/user/homebrew-repository` tap before installing the formula. `user/repo/formula` points to the `github.com/user/homebrew-repo/**/formula.rb` file here. +If it’s on GitHub, users can install any of your formulae with `brew install user/repository/formula`. Homebrew will automatically add your `github.com/user/homebrew-repository` tap before installing the formula. `user/repository/formula` points to the `github.com/user/homebrew-repository/**/formula.rb` file here. To install your tap without installing any formula at the same time, users can add it with the [`brew tap` command](Taps.md). If it’s on GitHub, they can use `brew tap user/repository`, where `user` is your GitHub username and `homebrew-repository` is your repository. If it’s hosted outside of GitHub, they have to use `brew tap user/repo `, where `user` and `repository` will be used to refer to your tap and `` is your Git clone URL. -Users can then install your formulae either with `brew install foo` if there’s no core formula with the same name, or with `brew install user/repo/foo` to avoid conflicts. +Users can then install your formulae either with `brew install foo` if there’s no core formula with the same name, or with `brew install user/repository/foo` to avoid conflicts. ## Maintaining a tap From 83c1ed68f3d44b86964d8b25c318a401668b0b48 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Fri, 5 Sep 2025 18:47:03 +0100 Subject: [PATCH 2/2] Apply suggestion from @samford Co-authored-by: Sam Ford <1584702+samford@users.noreply.github.com> --- docs/How-to-Create-and-Maintain-a-Tap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index f43917edeb..11e38a722b 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -23,7 +23,7 @@ Initialized empty Git repository in /opt/homebrew/Library/Taps/$YOUR_GITHUB_USER Next, you can push it to a new GitHub repository: ```console -$ gh repo create $YOUR_GITHUB_USERNAME/homebrew-tap --push --public --source "$(brew --repository $YOUR_GITHUB_USERNAME/homebrew-tap)" +$ gh repo create $YOUR_GITHUB_USERNAME/homebrew-tap --push --public --source "$(brew --repository $YOUR_GITHUB_USERNAME/homebrew-tap)" ✓ Created repository $YOUR_GITHUB_USERNAME/homebrew-tap on github.com https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap ✓ Added remote https://github.com/$YOUR_GITHUB_USERNAME/homebrew-tap.git