Brewing an old batch of Tmux

This article chronicles the time I ran brew upgrade and regretted it. The target audience of this article is OS X users. There is potential for additional enjoyment if you are also a tmux user. The goal of this article is empower brew users to install the software they would like to install even when it is not readily accessible.

Tmux is an impressive piece of software and a centerpiece of my daily workflow. It is a shame, however, that its maintainers do not prescribe to the conventions outlined by semver. In short, this means that with each version upgrade, consumers do not know that a version change from 2.4 to 2.5 may introduce a breaking API change. This becomes a problem when your dotfiles depend on APIs maintaining a reliable shape. In my case, when I upgraded from version 2.3 to 2.5, I lost a few of the keybindings that I use frequently.

Of course the morally righteous thing to do is to learn the new APIs and update your dotfiles accordingly. But what happens when you introduce breaking changes to your tooling while you’re at work in the middle of a task? One task can quickly turn into dozens and next thing you know you’re shaving a yak. Sometimes the expedient thing to do is rollback the tool to a previously working version and get on with your day.

Let’s outline the steps to accomplish this for Tmux.

Step 1: Uninstall Tmux 2.5

$ brew uninstall tmux

Step 2: Install Tmux 2.3

$ brew install tmux@2.3
Error: No available formula with the name "tmux@2.3"

Alas... If you thought this was going to be straightforward — like I initially did — it is not. Sometimes rolling back using brew is this simple. However, when brew cannot find the formula for the previous version, you must stress-test the extent of your brew-fu.

Step 3: Scavenge

Since brew cannot locate version 2.3 on its own, we need to find the commit hash for the formula ourselves. Once found, we can point brew to this formula using the checksum generated by git.

Head to homebrew-core on GitHub. Press t on the GitHub homepage and search for “tmux”. Click the source file for Formula/tmux.rb. Once here browse through the History tab for any commit that references version 2.3. If GitHub complains that the history is “taking too long to generate”, clone the repository to your local disk and run:

$ git clone git@github.com:Homebrew/homebrew-core.git
$ cd homebrew-core
$ git log master -- Formula/tmux.rb

Step 4: Install Tmux 2.3 (round 2)

$ brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/<COMMIT-SHA>/Formula/tmux.rb

Substitute the commit checksum you grabbed from the git log into the placeholder marked <COMMIT-SHA>.

Let’s ensure that the installation succeeded:

$ tmux -V
tmux 2.3

Step 5: Pin the version

Now that we have successfully rolled-back, we need to prevent ourselves from unintentionally upgrading Tmux again. To accomplish this, we need to pin the version:

$ brew pin tmux

Lastly, let’s ensure that the pinning succeeded:

$ brew list --pinned
tmux

Voila! Hopefully this article helped those looking for finer-grain control over homebrew. Perhaps more importantly, it is important to realize that our tools are intended to help us, but sometimes it feels like they get in our way. Knowledge is the ultimate antidote to relieve these aggravations.

As for those that are unfamiliar with Tmux, it is worth checking out. As always, thanks for reading.