Make your first Homebrew tap

Shinichi Okada

Follow

May 26 · 5 min read

Introduction

Homebrew is the missing package manager for macOS. It installs packages with a simple command like brew install curl. Homebrew taps are third-party repositories. By creating a Homebrew tap formula, users can install and use your repo.

In this article, you will learn how to create a simple Homebrew tap. I used my gitstart for this article. Gitstart is a bash script to create a Git repo. It contains only one file.

Step 1: Git Tag

You need to add a Git tag to your repo:

$ git tag -a v0.0.2 -m "version 0.2.0"

Push your tag to the remote repo:

$ git push origin v0.2.0

Step 2. Create a New Release

On your GitHub repo, click Create a new release.

In the Tag version, select the latest version and write the description of the release.

Step 3. Run Brew Create

Find the source code (tar.gz) and copy the link address:

Run brew create your-link and replace your-link with your copied link.

For example:

$ brew create https://github.com/shinokada/gitstart/archive/refs/tags/0.2.0.tar.gz

It will show the content of the created file.

If your default editor is VIM, quit the program by using :q.

Note the file path in outputs. In this case, the file path is:

"/opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula/gitstart.rb"

Step 4. Create a New GitHub Repo

Create a new GitHub repo. The naming should have “homebrew-” at the beginning.

For example, mine is homebrew-gitstart.

In the new repo, copy or move the created file to your repo:

Line 2: Add a description of your repo.
Line 3: You must add a homepage.
Line 4: This should be auto-filled in. If not, use the copied link in the previous section.
Line 5: Replace the sha256 value with yours.
Line 6: Add your license. MIT is a common license for an open source repo.
Line 8–10: State your dependencies.
Line 12–14: Use bin.install to move the file gitstart into the formula’s bin directory (/usr/local/Cellar/pkg/0.1/bin) and make it executable (chmod 0555 foo).

If you have directories, you can use Dir["./lib"] to install directories:

def install    
    bin.install "gitstart"    
    bin.install Dir["./lib"]    
    bin.install Dir["./files"]  
end

Step 5. Add, Commit, and Push

Once it is ready, add the file, commit, and push.

$ git add .
$ git commit -m "Version 0.2.0"
$ git push

Step 6. Remove gitstart.rb From the Homebrew Formula dir

You need to remove the gitstart.rb file from Formula dir.

$ rm  /opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula/gitstart.rb

Step 7. Tap and Install

Now your tap is ready.

Run using the following command:

$ brew tap shinokada/gitstart

Then run brew install gitstart.

Check if it is installed by running which gitstart. You can uninstall it using brew uninstall gitstart.

Update routine

Step 1.

Add and push a new version.

$ git tag -a v0.2.1 -m "version 0.2.1"
$ git push origin v0.2.1

Repeat Step 2 above:

When you update your repo, you need to create a new sha256.

$ brew create https://github.com/shinokada/gitstart/archive/refs/tags/v0.2.1tar.gz

Update the URL value and copy and paste the new sha256 value to your homebrew-gitstart, which you created in Step 4.

Step 2. Remove gitstart.rb from the homebrew Formula dir

Same as Step 6 in the previous section. Remove gitstart.rb from the homebrew formula directory. Otherwise, it will conflict with your repo:

$ rm /opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula/gitstart.rb

Step 3. Run brew upgrade

$ brew upgrade

Run brew install gitstart:

Check the new version:

$ gitstart -v
0.2.2

Tips

untap

When you update homebrew-your-repo, you may need to uninstall and untap the local file:

$ brew uninstall --force backpack_install
$ brew untap shinokada/gitstart
Untapping shinokada/gitstart...
Untapped 1 formula (13 files, 7.1KB).

brew uninstall uninstalls a package but not the homebrew.rb file. By running brew untap, it removes the homebrew.rb file.

Then you can tap your new repository:

$ brew tap shinokada/gitstart

alias

When you are developing locally you need to link/unlink your local file. I added an alias as follows:

alias addsym='brew uninstall gitstart && ln -sf ~/Bash_Projects/Gitstart/gitstart-repo/gitstart ~/bin/gitstart'
alias rmsym='rm ~/bin/gitstart && brew upgrade && brew install gitstart'

The addsym uninstalls the gitstart formula from Homebrew and adds a symlink to ~/bin directory. (I exported the path ~/bin in the .zshrc file.)

The rmsym removes the symlink and runs brew upgrade and brew install gitstart.

What’s Next?

Homebrew’s Formula Cookbook has more detailed instructions. Homebrew Ruby API on Class Formula provides all methods and attributes. If you are using a Make file, Learn Makefiles is a great place to start. You can browse Homebrew-core formula to learn how experienced developers make their formula.

Conclusion

There has more information about Hombrew Taps. My repo is a simple bash script, but if your repo is more complex, you may need to check the build system, specifying conflicts with other formulae, add a test to the formula, and more.

I hope this article made it clear how to create your Homebrew formula. Please let me know how it goes and post your questions or comments.

Happy coding.

If you like my article and would like to receive my newsletter, please sign up.

References

• https://docs.brew.sh/Formula-Cookbook
• http://sophyonline.com/blog/index.php/2018/03/19/create-a-local-formula-for-homebrew-tap-it/