How to Publish a Bash Script to Homebrew

Homebrew is a popular package manager for macOS (and Linux) that allows you to distribute scripts and tools easily. In this guide, we’ll walk through how to publish a bash script to Homebrew so that others can install it via brew install.

1. Create the Repository for Your Script

The first step is to create a GitHub repository for your script.

1. Go to GitHub and create a new repository. Name it something relevant to your script (e.g., block-site).
2. Clone the repository to your local machine:

   git clone https://github.com/yourusername/block-site.git
   

3. Inside the repository, add your bash script (e.g., block_site.sh).
4. Commit and push the script:

   git add block_site.sh
   git commit -m "Add block site script"
   git push origin main
   

2. Create a Release for the Repository

Once your script is in the repository, you’ll need to create a versioned release. This is essential for Homebrew to fetch your script.

1. Go to the “Releases” tab in your repository and click “Create a new release.”
2. Tag the release with a version (e.g., v1.0.0) and give it a title and description.
3. Publish the release. The release will generate a downloadable .tar.gz file, which Homebrew uses.

3. Create Another Repository homebrew-formulae

Next, you need to create a separate repository to host your Homebrew formula.

1. Create a new repository called homebrew-formulae on GitHub.
2. Clone this repository to your local machine:

   git clone https://github.com/yourusername/homebrew-formulae.git
   

3. This repository will store the Ruby formula that Homebrew will use to install your script.

4. Add a Formula to username/homebrew-formulae

Now, let’s create a formula that Homebrew will use to install your bash script. Inside the homebrew-formulae repository, create a Ruby file (e.g., block-site.rb) with the following content:

class BlockSite < Formula
  desc "Script to block and unblock websites by modifying /etc/hosts"
  homepage "https://github.com/yourusername/block-site"
  url "https://github.com/yourusername/block-site/archive/v1.0.0.tar.gz"
  sha256 "522bb30562f3d5b5a8b15ac4e5f8b2392544f64908e1ec20c7ac456c03574e0a"
  version "1.0.0"

  def install
    bin.install "block_site.sh" => "block-site"
  end

  def caveats
    <<~EOS
      This script requires sudo privileges to modify the /etc/hosts file.
      Use it as follows:
      - Block a site: block-site --block domain.com
      - Unblock a site: block-site --unblock domain.com
    EOS
  end
end

Explanation of the Formula

• desc: A brief description of what your script does.
• homepage: The URL of your GitHub repository.
• url: The URL to the .tar.gz file generated by the release. Update this with your actual repository URL.
• sha256: The SHA-256 checksum of the .tar.gz file. This ensures that the file hasn’t been tampered with.
• version: The version of your script, matching the release tag.
• install: This tells Homebrew how to install your script. The bin.install command installs your bash script as an executable named block-site.
• caveats: Any special instructions or notes for the user.

Generating the sha256 Hash

To get the SHA-256 checksum, download the .tar.gz file from the GitHub release and run the following command:

shasum -a 256 v1.0.0.tar.gz

Copy the resulting hash and paste it into the sha256 field in the formula.

5. Tapping & Installing

To make the formula available for Homebrew users, they’ll need to “tap” your repository and install your script.

1. Push your formula to the homebrew-formulae repository:

   git add block-site.rb
   git commit -m "Add block-site formula"
   git push origin main
   

2. Users can now tap your repository by running:

   brew tap yourusername/formulae
   

3. Once the repository is tapped, they can install your script with:

   brew install block-site
   

Final Notes

Your bash script is now packaged and distributed via Homebrew! Users can easily install it with a single command, making your tool more accessible. As you update your script, simply create new releases and update the formula accordingly.

Happy scripting!

• Previous
  What is the Leader Key in Neovim?
• Next
  Week 14 Google Summer of Code @ LLVM