Downgrade to a Specific Version of an Application in Homebrew

I always have the habit of updating all software to the latest version. However, while writing a blog, I discovered that after updating Hugo, there were issues running it locally.

ERROR deprecated: site config key paginate was deprecated in Hugo v0.128.0 and subsequently removed. Use pagination.pagerSize instead.
ERROR deprecated: resources.ToCSS was deprecated in Hugo v0.128.0 and subsequently removed. Use css.Sass instead.
ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and subsequently removed. Use hugo.IsMultilingual instead.
ERROR deprecated: .Site.Author was deprecated in Hugo v0.124.0 and subsequently removed. Implement taxonomy 'author' or use .Site.Params.Author instead.

From the error messages, it’s clear that Hugo introduced breaking changes in the update. After the upgrade, some fields and methods were directly removed. At first glance, the error messages seemed helpful, offering alternative fields. However, after making those replacements, I realized it wasn’t as simple as it seemed. The site wouldn’t run. So, I had to downgrade Hugo to its previous version.

Here are the steps I followed:

  1. Run brew info hugo to find the repository and path of the application you want to downgrade.
    1. In my case, I used a mirror. The original repo is hosted on GitHub.
  2. Go to the corresponding repository on GitHub and locate the relevant file.
    1. The file path can be referenced here: https://github.com/Homebrew/homebrew-core/blob/master/Formula/h/hugo.rb
  3. Check the commit history of this file and find the commit ID of the version you want to downgrade to.
    1. Based on the commit ID, you can identify the version, which is usually submitted by the bot BrewTestBot.
  4. Once you have the commit ID, you can retrieve the URL of the formula file and its content.
    1. Example: https://github.com/Homebrew/homebrew-core/blob/2fd8dba871a6a5412fa7c00b12ac99b5738cd199/Formula/h/hugo.rb
    2. Raw content: https://raw.githubusercontent.com/Homebrew/homebrew-core/2fd8dba871a6a5412fa7c00b12ac99b5738cd199/Formula/h/hugo.rb
    3. Replace the commit ID and app name accordingly to get the correct URL.
  5. According to some online guides, you can directly install using the URL with brew install url.
    1. However, when I tried this, I encountered an error: Error: Non-checksummed download of hugo formula file from an arbitrary URL is unsupported! brew extract or brew create and brew tap-new to create a formula file in a tap on GitHub instead.
  6. Instead, I copied the formula file’s content, saved it locally, and then installed it using brew install ./hugo.rb. The installation was successful.

After successfully downgrading the Homebrew application, you can lock the version using brew pin hugo to prevent future upgrades.


After encountering the failure with the install url method, I found another approach for downgrading, which also seemed feasible. However, I ran into errors while executing the build script locally. Still, it might be worth referencing.

1
2
3
4
brew tap-new $USER/local-cmake
brew tap homebrew/core --force
brew extract --version=3.31.1 cmake $USER/local-cmake
brew install $USER/local-cmake/cmake@3.31.1

Here’s an explanation of these commands:

These four Homebrew commands aim to create a local tap and install a specific version of CMake. Let me explain each command:

1. brew tap-new $USER/local-cmake

This command creates a new tap (software repository). $USER is an environment variable representing the current username, so the tap will be named "your-username/local-cmake."

  • Purpose: Create a new local tap to store custom formulae.
  • Result: A new tap structure is created at $(brew --repo)/Library/Taps/$USER/homebrew-local-cmake.

2. brew tap homebrew/core --force

This command forcibly taps Homebrew's core repository.

  • Purpose: Ensure the homebrew/core repository (which contains official formulae) is properly tapped. The --force flag ensures the action is performed even if the tap already exists.
  • Result: Ensures access to the formulae in homebrew/core, which is necessary for extracting the CMake formula.

3. brew extract --version=3.31.1 cmake $USER/local-cmake

This command extracts a specific version of the CMake formula from homebrew/core to your local tap.

  • Purpose: Extract the CMake formula for version 3.31.1 from the official repository and place it in your newly created local tap.
  • Result: A cmake@3.31.1.rb formula file is created in your local tap.

4. brew install $USER/local-cmake/cmake@3.31.1

This command installs the specific version of CMake from your local tap.

  • Purpose: Use the extracted formula to install CMake version 3.31.1.
  • Result: CMake version 3.31.1 is installed on your system.