So here is the 2026 updated guide for asdf: same tool, same philosophy, new binary, new commands. Whether you are upgrading or starting fresh, this will get you productive with asdf.

Why asdf

Say you work as a developer for a company whose stack is Ruby on Rails on the backend and React on the frontend. The backend is not one repository but several, and they do not all run the same Ruby version; the frontend repositories are in the same boat with Node.js.

To manage the different versions of Ruby you could use rbenv, for Node.js there is nvm, and when Python enters the picture for some machine learning tasks, along comes pyenv. Three tools with three slightly different command syntaxes is already a burden, and it only gets worse when you want to build a side project with Elixir or learn some Rust.

asdf replaces all of them. Thanks to its plugin system, one tool with one set of commands can install and manage versions of almost any programming language, along with plenty of other CLI tools. And if a language or tool does not have a plugin yet, you can create one yourself.

What Changed in the Go Rewrite

In early 2025, asdf was rewritten from the ground up in Go and shipped as version 0.16.0. Until then, asdf was implemented in shell scripts, and the asdf command you ran was actually a shell function sourced into your session. It is now a single compiled binary.

I will admit the rewrite did not win me over right away. The changes felt dramatic: suddenly everything was new in a tool I knew inside out. The way the upgrade was pushed did not help either. After 0.16.0 came out, my still-working installation started printing a long red warning on every single asdf command, telling me to migrate. Since every tool installed through asdf runs through asdf, that wall of red text greeted every ruby and node invocation too, even though, by the notice’s own admission, the old version “works as it did in asdf version 0.15.0 and older”. Nothing was broken; I was just being nagged.

Having lived with the new asdf for a while, though, I have come around. Everything feels snappier, though speed was never my complaint after years of daily use. What won me over were the quieter wins from the switch to a real binary: you now install and upgrade asdf through your package manager like any other tool, and there is nothing to source into your shell config.

A rewrite of the internals alone would not warrant a new guide. The breaking changes do:

• asdf global and asdf local are gone, replaced by a single asdf set command with flags for the different scopes.
• asdf shell is gone. A binary cannot modify the environment of your running shell, so per-session overrides are now done with plain environment variables.
• Hyphenated commands lost their hyphens: asdf plugin-add became asdf plugin add, and asdf list-all became asdf list all.
• asdf update is gone. You upgrade asdf itself through your package manager instead.
• The shell setup changed. Instead of sourcing asdf.sh in your shell config, you put the shims directory on your PATH.

Do not worry if some of these terms mean nothing to you yet: they are all covered below. The latest release as of this writing is v0.20.0, which is the version this guide uses.

Install asdf

The simplest way to install asdf on macOS is with Homebrew:

brew install asdf

Then add the asdf shims directory to your PATH (shims are explained in Under the Hood below). For Zsh, add the following to the bottom of ~/.zshrc:

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Open a new terminal tab and you should be ready to use asdf :tada:

In the previous version of this guide, I recommended installing asdf by cloning its Git repository and sourcing asdf.sh from your shell config. Neither applies anymore: asdf is a compiled binary now, so there is nothing to source. If you are upgrading from a pre-0.16 installation, remove the old . $HOME/.asdf/asdf.sh line from your ~/.zshrc when you add the PATH line above.

Homebrew is not the only option. You can also download a prebuilt binary from the asdf releases page and put it somewhere on your PATH, or install it with go install if you already have Go set up. If you use Bash, Fish or another shell, refer to the Getting Started guide for the matching setup instructions.

Manage Plugins

Before you can install Ruby, Node.js or anything else, you need to add the appropriate plugins. Plugins are how asdf knows how to handle each language or tool:

asdf plugin add ruby
asdf plugin add nodejs

For plugins listed in the asdf plugins repository, the short name above is all you need. A plugin that is not listed there can still be added by passing its Git URL, shown here with the Node.js plugin standing in as an example:

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

In practice you will rarely need this: the plugins repository covers hundreds of tools.

You can list the plugins you have installed:

asdf plugin list

Or list all the plugins available in the plugins repository:

asdf plugin list all

Plugins are also where new version definitions come from. If a freshly released version does not show up in asdf list all, update your plugins first:

asdf plugin update --all

Manage Language Versions

Install Versions

Suppose we want the current stable Ruby and the current LTS release of Node.js, which are 4.0.6 and 24.18.0 respectively as of this writing:

asdf install ruby 4.0.6
asdf install nodejs 24.18.0

You can browse the available versions first:

asdf list all ruby

Or skip looking up version numbers entirely:

asdf install nodejs latest

To see which versions you already have installed, and to remove one you no longer need:

asdf list ruby
asdf uninstall ruby 3.3.6

If a version fails to install, check the GitHub repository of the plugin: known issues and their fixes are usually documented there.

Set Versions

This is the biggest change from the old command set. Where you previously chose between asdf global and asdf local, there is now a single command:

asdf set nodejs 24.18.0

By default, asdf set writes to a .tool-versions file in the current directory, which is exactly what asdf local used to do. Run it in a project directory and that project is pinned to Node.js 24.18.0, regardless of what other projects use.

To set a user-wide default version, the equivalent of the old asdf global, pass the -u flag (for the home directory):

asdf set -u nodejs 24.18.0
asdf set -u ruby 4.0.6

The asdf team dropped the “global” terminology on purpose: it was never truly global, just a fallback in your home directory that any project could override. The new naming makes that explicit, and to me this is one place where the rewrite improved not just the implementation but the logic.

There is also a -p flag, which updates the nearest existing .tool-versions file in a parent directory. This is handy in a monorepo, where you might run the command deep inside a subdirectory but want to update the version pinned at the repository root.

Finally, if you want a tool to fall back to whatever macOS or Homebrew provides, you can set its version to system:

asdf set ruby system

Session Overrides

The old guide had a section on asdf shell, which set a version for just the current shell session. That command is gone, but the underlying mechanism survives: asdf still honours an environment variable named ASDF_${TOOL}_VERSION, and it takes precedence over any .tool-versions file.

Say a legacy client app in your project only runs on an older Node.js. Instead of touching any files, you can override the version for one shell session:

export ASDF_NODEJS_VERSION=20.19.0

Or for a single command:

ASDF_NODEJS_VERSION=20.19.0 npm start

Other sessions are unaffected, and closing the terminal cleans up after you.

Quick Recap

asdf lets you pin versions per directory through .tool-versions files, set user-wide defaults with asdf set -u, and override everything per session or per command with an environment variable. That should be flexible enough for most situations you will ever encounter.

Under the Hood

If you are new to asdf, this might sound like magic, but how asdf works is actually quite straightforward, and the Go rewrite made it easier to explain.

Shims

The PATH entry you added during installation points at a directory of shims. A shim is a tiny executable that sits in front of the real one: when you run node, you are actually running the node shim, which asks asdf to resolve the right Node.js version and then executes that version’s real node binary. This is why there is nothing to source in your shell config anymore, and why any program, not just your interactive shell, picks up the correct versions.

One maintenance command worth knowing here is asdf reshim. Shims are generated when a version is installed, so when a package you add later ships its own executable, think gem install rubocop or a global npm package, the shell may not find the new command. Regenerate the shims for that plugin and you are back in business:

asdf reshim ruby

Version Resolution

When a shim resolves a version, asdf checks the following, in order:

1. The ASDF_${TOOL}_VERSION environment variable.
2. A .tool-versions file in the current directory, then the parent directory, then the parent’s parent, all the way up.
3. The .tool-versions file in your home directory, which is where asdf set -u writes.

If you enable the legacy_version_file option described in Coexist with Legacy Tools below, legacy files such as .ruby-version and .nvmrc are also consulted during step 2, right after .tool-versions.

The .tool-versions file itself is plain text, one tool per line:

cat ~/.tool-versions
nodejs 24.18.0
ruby 4.0.6

If you are working on a personal project or your team has adopted asdf, it is a very good idea to commit the project’s .tool-versions file to version control. If your team has not agreed on asdf yet, add it to .gitignore instead, and see Coexist with Legacy Tools below.

Current Versions

To see which versions are active in the current directory and where they come from, run asdf current:

asdf current
Name    Version    Source                                    Installed
nodejs  24.18.0    /Users/username/project/.tool-versions    true
ruby    4.0.6      /Users/username/.tool-versions            true

The Source column shows exactly which .tool-versions file each version was resolved from, which makes it easy to figure out where a surprising version is coming from.

Use asdf in a Team

Coming back to the scenario from the beginning of this post: suppose your team has adopted asdf (and if it has not yet, the next section is for you). Everyone still needs the correct versions installed when they start working on a project for the first time.

You could read the project’s .tool-versions file and install each version by hand, but there is no need. Run asdf install in the project directory without any arguments:

asdf install

asdf reads .tool-versions and installs anything that is missing. One command, and a new team member is ready to run the project. This remains one of my favourite asdf features, and it works exactly as it did before the rewrite.

Coexist with Legacy Tools

If you are sold on asdf but your team still uses rbenv, nvm and friends, there is a configuration option that lets you meet them where they are. Create a .asdfrc file in your home directory with the following content:

legacy_version_file = yes

With this set, asdf plugins will read the version files of other version managers, for example .ruby-version for rbenv and .nvmrc for nvm. Your teammates keep their existing tools and version files, and you get to use asdf against the same repositories.

Note: not all plugins support this feature. If you rely on this behaviour, check the documentation of the plugins you use.

What About mise?

A 2026 guide to asdf would not be complete without mentioning mise. mise started life as a Rust reimplementation of asdf, and has grown into a broader tool that also manages environment variables and project tasks. It understands .tool-versions files and can use asdf plugins, so the two coexist well, and the asdf documentation itself links to a comparison between them.

I have stuck with asdf: it does one thing well, and I have used it for years. Speed used to be the complaint you would hear most often, and mise is still faster on paper, but with the 2x to 7x speedups from the Go rewrite, there is no practical difference in daily use. If you want an all-in-one tool, though, mise is a good alternative.

Summary

In this post, I covered:

• what changed in the asdf rewrite in Go
• how to install asdf
• how to add plugins
• how to manage versions with asdf set
• how shims and version resolution work under the hood
• how asdf fits in a team setting
• how to use asdf alongside legacy tools

The commands may have changed since 2021, but the reasons I recommended asdf back then have not: one tool, one set of commands, and a .tool-versions file that makes sharing language versions across a team effortless. If you run into anything this guide does not cover, the asdf documentation remains your best first stop.

Late last year I joined a new company. In my first week, poking around the Phoenix app I’d be working on, I found this in config/test.exs:

config :bcrypt_elixir, :log_rounds, 1

Nobody on the team had written that line. The installer that scaffolded the app’s authentication generated it, as Phoenix’s own phx.gen.auth does for every new app. The bcrypt_elixir docs recommend the same thing plainly.

I winced. Only months earlier, at my previous company, I had spent weeks “discovering” this exact fix: profiling, benchmarks, rounds of factory rewrites, using the best available model at the time.

I even had a post drafted about that journey, documenting what felt like a solid performance win. It had been waiting on finishing touches I never got round to, and after that week they stopped mattering. So here it is instead, rewritten as a confession.

The Slow Suite

Rewind to my previous company. Our main Phoenix application had no reliable test suite. Some tests existed, but many failed for various reasons. That meant we couldn’t run them on CI, so they offered little assurance that new changes wouldn’t break existing functionality.

We were a tiny team, just three developers, hammered by an endless stream of feature requests and bug reports. My colleagues stayed underwater in that stream. But I kept coming back to the Chinese saying 工欲善其事，必先利其器: to do good work, one must first sharpen one’s tools. So I took the test suite on.

I fixed some failures, temporarily skipped others, and got the suite green. Then I set up a Jenkins pipeline so every change ran the tests. A real step forward, with a catch.

The full suite took 285 seconds on my laptop, and even longer on CI. Nearly five minutes per run meant I avoided running it locally, and every build was a long wait.

The slowness bothered me, but I had no clear picture of where the time was going and no obvious plan of attack. I couldn’t justify spending days on optimization without a concrete goal, so we lived with it for a long time.

What eventually changed the calculus was AI-assisted coding. With models finally capable of serious work on a real codebase, an open-ended optimization effort stopped looking like a time sink I couldn’t afford.

Finding the Bottleneck

Before optimizing anything, I profiled. The culprit revealed itself quickly: Bcrypt. Every call to Bcrypt.hash_pwd_salt() took 100–200ms.

That might not sound like much, until you realize the suite called it hundreds of times. Every insert(:user), insert(:customer), and insert(:provider) in our ExMachina factories hashed a password:

def user_factory() do
  %User{
    username: Internet.user_name(),
    email: Internet.email(),
    password_hash: Bcrypt.hash_pwd_salt("test_password_123")  # 100-200ms each!
  }
end

Multiply that by hundreds of test setups, and the bottleneck was clear.

Optimizing the Hard Way

The work happened in Claude Code, on Opus 4, the strongest model of the day. My instruction was direct: benchmark the factories and optimize away the repeated hashing.

And that is exactly what it did. Diligently. We pre-computed password hashes as module constants and reused them for all default test data, falling back to real hashing only for custom passwords:

defmodule Admin.UserFactory do
  # Pre-computed hash for the default test password
  @user_test_password "test_password_123"
  @user_test_password_hash "$2b$12$MFkURc/nMXU5HQxgWURhauA4tegLJKvJPlOtvQxzvQ35oz0q/Nrj2"

  def user_factory(attrs) do
    password = Map.get(attrs, :password, @user_test_password)

    # Use pre-computed hash for default, generate for custom passwords
    password_hash = Map.get_lazy(attrs, :password_hash, fn ->
      if password == @user_test_password do
        @user_test_password_hash  # Fast: pre-computed
      else
        Bcrypt.hash_pwd_salt(password)  # Slow: on-demand
      end
    end)

    %User{
      username: Internet.user_name(),
      email: Internet.email(),
      password_hash: password_hash
    }
  end
end

We applied this pattern across every authentication-related factory: users, customers, providers. Each got its own default test password and pre-computed hash.

The results?

# Before
$ mix test
....................................
Finished in 285.6 seconds

# After first optimization
$ mix test
....................................
Finished in 105.2 seconds

~63% improvement. Nearly three minutes off the suite. Success!

But notice what didn’t happen. The model knew the goal was a faster test suite, and, as I would soon find out, it knew the standard fix. Yet across all those rounds of benchmarking and refactoring, it never suggested log_rounds, or even checking the bcrypt_elixir docs. I had asked it to optimize factories, so it optimized factories.

And something felt wrong to me. We had added real complexity (constants, conditionals, helper functions across multiple factory files) for a problem that every Elixir app hashing passwords must share. A problem this common shouldn’t need solving the hard way.

The Question That Changed Everything

If the problem was that common, someone must have solved it properly already. So I asked a different question: “Is there a cheaper alternative to Bcrypt.hash_pwd_salt for tests?”

The model came back with the fix almost immediately: log_rounds. It had known all along. It was just never asked.

Bcrypt is intentionally slow. That’s the whole point: by making password hashing computationally expensive, it protects against brute-force attacks. The log_rounds parameter controls this cost:

• log_rounds: 12 means 2^12 = 4,096 iterations
• log_rounds: 10 means 2^10 = 1,024 iterations
• log_rounds: 4 means 2^4 = 16 iterations

Each increment doubles the computational work. The default of 12 is right for production. But test passwords are ephemeral: they exist only during a test run and are immediately discarded. They only need to be valid hashes, not brute-force resistant.

And crucially, log_rounds can be configured per environment:

# config/test.exs
config :bcrypt_elixir, :log_rounds, 4

One line. I reverted every factory change (the constants, the conditionals, the helpers) and the factories went back to their simple, original form:

def user_factory(attrs) do
  password = Map.get_lazy(attrs, :password, fn -> random_password() end)

  %User{
    username: Internet.user_name(),
    email: Internet.email(),
    password_hash: Bcrypt.hash_pwd_salt(password)  # Now fast!
  }
end

The results?

# After second optimization
$ mix test
....................................
Finished in 50.1 seconds

From 285 seconds to 50: an 82% speedup, 5.7× faster, with less code than we started with. Production and dev configs stayed at 12, so there was no security compromise anywhere.

It Shouldn’t Have Been a Discovery

I drafted this story a couple of months after the fix. Knowing no better, I had framed it as a reasonable approach to a tough problem, with a big discovery at the end. It needed only some finishing touches, but life got busy, and the draft sat.

Then came the new company, and that config line staring at me from a test.exs nobody had to write. I checked the bcrypt_elixir README. There it was: a low log_rounds setting for tests, documented clearly, all along.

I was taken aback. My hard-won discovery was just boilerplate, knowledge so standard that app generators write it for you. For a good while I wasn’t sure this post deserved publishing at all.

But that is exactly why it does. A tiny team lived with a five-minute test suite for years. The best model of the day ran rounds of benchmarks without once suggesting the docs. The fix was one documented line. The failure mode is the story.

What I Actually Learned

The bottleneck was the question, not the intelligence. The model knew about log_rounds the entire time. Any of us could have found it in the README in five minutes. Nobody asked.

AI amplifies your framing; it doesn’t correct it. Asked to optimize factories, the model optimized factories: skillfully, and entirely within my flawed premise. Knowing my end goal didn’t help; my instructions had already chosen the approach. The quality of the answer is capped by the quality of the question.

Read the library docs before optimizing around the library. Bcrypt was never the problem. Using production settings in tests was, and the library authors had anticipated exactly that.

Listen to the “this is too hard” feeling. The pre-computed-hash detour wasn’t wasted. The discomfort of all that added complexity is what pushed me to stop and ask a better question.

Config can beat code. If your Elixir test suite is slow and uses Bcrypt, the fix is one line, and if your app’s authentication came from a generator like phx.gen.auth, it is probably already there:

# config/test.exs
config :bcrypt_elixir, :log_rounds, 1

Generators write 1; the bcrypt_elixir docs suggest 4, which is what we used. Either way, hashing becomes effectively free in tests.

Sometimes the best optimization isn’t clever code, or even a smarter model. It’s noticing that a problem is too common to be this hard, then asking the question that assumes someone already solved it.

Examples below use a ZSA Moonlander (zsa/moonlander) and a keymap called mykeymap. Swap in your own board and keymap name as you go.

Quick start

1. Install the toolchain: curl -fsSL https://install.qmk.fm | sh
2. Fetch the QMK source: qmk setup (already have a clone? qmk config user.qmk_home=/path/to/qmk_firmware instead)
3. Sanity-check: qmk doctor (optional if you ran qmk setup, which runs it for you)
4. Keep your keymap in its own repo via External Userspace (details below)
5. Build: qmk compile -kb zsa/moonlander -km mykeymap
6. Flash: qmk flash -kb zsa/moonlander -km mykeymap, then drop the board into its bootloader.

Setting up QMK (recommended)

What you’re actually installing

The modern setup keeps everything tidy and self-contained, well away from your system Python and your day-to-day Homebrew packages. Three pieces get installed, all into user space:

• The qmk CLI, running inside its own uv-managed Python environment, so a Python upgrade somewhere else on your machine cannot break it.
• The compilers (ARM, AVR, RISC-V), as a prebuilt bundle that QMK maintains and ships itself. You do not have to hunt down cross-compilers or babysit their versions.
• The flashing utilities (dfu-util, avrdude, and friends), bundled right alongside.

When it is done, here is where things live by default, worth knowing so nothing feels like a black box:

• ~/.local/bin/qmk: the CLI, a symlink into ~/.local/share/uv/tools/qmk/
• ~/.local/bin/uv: the uv tool manager, if the script installed it
• ~/Library/Application Support/qmk/: the compilers and flashing tools
• ~/Library/Application Support/qmk/qmk.ini: your CLI config

1. Install the CLI and toolchains

One line does it:

curl -fsSL https://install.qmk.fm | sh

Yes, it is a curl … | sh, but it is the genuine official installer: all it does is fetch QMK’s bootstrap script and run it. It gives you a 10-second countdown before touching anything (hit Ctrl+C if you change your mind), then installs the three pieces above.

If you already have some of the prerequisites and do not want the installer fussing with them, you can opt out of individual steps. The handiest one on a machine already set up for development keeps it away from your Homebrew packages:

curl -fsSL https://install.qmk.fm | SKIP_PACKAGE_MANAGER=1 sh

SKIP_PACKAGE_MANAGER=1 stops the installer running brew update/brew upgrade, so it will not churn through your existing packages just to install a keyboard toolchain. (Already manage uv yourself? See Already manage uv yourself? below.)

Curious what else you can toggle? Run the installer with --help:

curl -fsSL https://install.qmk.fm | sh -s -- --help

One last thing before you move on: make sure ~/.local/bin is on your PATH, and ideally ahead of /opt/homebrew/bin, so the qmk you just installed is the one your shell actually reaches for. Drop this in your ~/.zshrc if it is not already there:

export PATH="$HOME/.local/bin:$PATH"

Then open a fresh shell and confirm with which qmk. You want to see /Users/you/.local/bin/qmk.

2. Tell the CLI where the QMK source lives

The CLI needs to know which qmk_firmware checkout to build from. That is the qmk_home setting.

If you do not have the QMK source yet, let QMK grab it for you (pass your GitHub fork’s username if you have one):

qmk setup

That clones the repo into ~/qmk_firmware, sets qmk_home, and runs qmk doctor to check things over.

Already cloned it somewhere of your own? Then skip qmk setup. Running it would just clone a redundant second copy. Point the CLI at what you have instead:

qmk config user.qmk_home=/Users/you/opensource/qmk_firmware

A quick read-back to confirm it stuck:

qmk config user.qmk_home

3. Check everything’s happy

qmk doctor

Think of this as your pre-flight check. A clean run means the CLI, the compilers, and qmk_home are all talking to each other. If something is missing or misconfigured, this is where it will tell you, much nicer than finding out halfway through a build.

4. Where to put your keymap

The recommendation here is External Userspace: keep your keymap in its own repository, completely outside the QMK tree. It is the approach that ages best: your personal config stays in a clean repo you own, and the QMK source stays pristine, so pulling in upstream updates never tangles with your changes.

The trick is that your external folder mirrors QMK’s own layout, so your keymap lives at:

<your-userspace>/keyboards/zsa/moonlander/keymaps/mykeymap/

You point QMK at the root of that userspace once:

qmk config user.overlay_dir=/path/to/your/userspace

From then on, the normal qmk compile command finds your keymap there automatically, with no difference in how you build. The full walkthrough, including how to scaffold the folder, lives in the QMK External Userspace docs.

If you would rather keep things dead simple and do not mind your keymap living inside the QMK checkout, the in-tree spot still works fine: drop the same keymaps/mykeymap/ folder under <qmk_home>/keyboards/zsa/moonlander/. A lot of people version just that folder as its own git repo to get some of the separation benefits. It is a perfectly good starting point for a single keymap. The snag shows up once you have more than one: because each keymap lives in its own folder, each becomes its own separate git repo, so managing several, possibly across different keyboards, means a repo to track for every one. Your keymaps also show up as local changes inside the QMK tree.

5. Build it

qmk compile -kb zsa/moonlander -km mykeymap

A green [OK] and a freshly generated .bin (or .hex on AVR boards) means you are good. You do not have to worry about the compiler being on your PATH. The CLI quietly wires up its bundled toolchain for you each time.

6. Flash it

qmk flash -kb zsa/moonlander -km mykeymap

This compiles and then sits waiting for your keyboard to show up in bootloader mode. To get a Moonlander there, do one of:

• Tap a QK_BOOT key, if your keymap has one mapped, or
• Press the physical reset button on top of the board.

The moment it enters the bootloader, qmk flash spots it and writes the firmware. Prefer a GUI? ZSA’s Keymapp flashes the same firmware without the command line.

Staying up to date

• The CLI is a uv tool, so uv tool upgrade qmk bumps it, or just re-run the install script.
• The toolchains refresh by re-running the install script whenever you want the latest bundle.
• The QMK source updates with a git pull in your qmk_home. Follow it with git submodule update --init --recursive to sync the submodules QMK pulls in. As long as you created your own keymap rather than updating the built-in keymaps in QMK, the pull stays conflict-free.

Already manage uv yourself?

If you already have uv installed, say via Homebrew or its standalone installer, there is no need to run the uv installer again. Pass SKIP_UV=1 so the QMK installer reuses the uv you already have:

curl -fsSL https://install.qmk.fm | SKIP_UV=1 sh

The only tradeoff is who owns updates: the qmk CLI still runs in its own uv-managed environment either way, but you keep uv itself current yourself (brew upgrade uv, or however you installed it) rather than re-running the QMK installer to refresh it.

If you set up QMK the old way (via Homebrew)

Most likely you installed qmk and the ARM/AVR compilers from a handful of third-party Homebrew taps (qmk/qmk, osx-cross/arm, osx-cross/avr). For years that was just a few brew tap and brew install commands that ran without fuss. But that has recently changed: Homebrew 6.0.0 introduced Tap Trust. Because a tap is a Git repo of Ruby that runs with your privileges, it now refuses to load a non-official tap until you have explicitly trusted it. It is a healthy change, it surfaces a trust decision that used to be made silently on your behalf, but it also turns the old setup into a fiddlier and slightly nervier process of vouching for several third-party sources before anything will install. The self-contained installer above sidesteps all of that, which is why the tap-based recipe has been retired.

Cleaning out the old Homebrew install

Do this after the modern setup is working (qmk doctor green and a successful compile), so you are never without a working build. The order matters: uninstall the formulae first, then remove the taps, then sweep up orphans.

brew uninstall --force qmk hid_bootloader_cli mdloader
brew uninstall arm-none-eabi-gcc@8 arm-none-eabi-binutils avr-gcc@8 avr-binutils
brew untap qmk/qmk osx-cross/arm osx-cross/avr
brew autoremove

A few notes so nothing surprises you:

• The --force on the first line clears out all installed versions at once.
• You cannot untap a tap while its formulae are still installed, which is why the untap comes after the uninstalls.
• brew autoremove mops up the long chain of dependencies the qmk formula originally dragged in (think Pillow → cairo/freetype/fonts, plus flashing tools like avrdude, dfu-util, dfu-programmer). It only removes things nothing else depends on, so shared tools like make, libusb, hidapi, python, and openssl stay put. Glance over its proposed list before confirming, and if you use something like dfu-util for non-QMK work, leave that one out of the uninstall.

Other gotchas you might run into

qmk: no such file or directory right after uninstalling. This one is a classic head-scratcher. zsh caches the full path of each command it has run, so after you delete a binary it keeps reaching for the old, now-gone path. Clear the cache and you are fine:

hash -r

(rehash works too, or just open a new terminal.)

qmk_home set to None, so you are building the wrong tree. If the CLI does not know where the QMK source lives, it falls back to ~/qmk_firmware, which might be empty or simply not the repo your keymap is in, and you will get baffling build results. Check it, then set it:

qmk config user.qmk_home
qmk config user.qmk_home=/Users/you/opensource/qmk_firmware

Quick reference

Where everything lives by default:

• CLI binary: ~/.local/bin/qmk, a symlink into ~/.local/share/uv/tools/qmk/
• Compilers and flashing tools: ~/Library/Application Support/qmk/
• CLI config: ~/Library/Application Support/qmk/qmk.ini
• QMK source: wherever user.qmk_home points
• Keymap (External Userspace): <overlay_dir>/keyboards/<vendor>/<board>/keymaps/<name>/
• Keymap (in-tree): <qmk_home>/keyboards/<vendor>/<board>/keymaps/<name>/

Handy sanity commands:

qmk doctor
which qmk
qmk config
qmk compile -kb zsa/moonlander -km mykeymap

Prerequisites

• Vim or Neovim with coc.nvim installed
• Elixir and Erlang installed (ideally managed via asdf)

Step 1: Install ElixirLS

Clone and build ElixirLS:

git clone https://github.com/elixir-lsp/elixir-ls.git ~/.elixir-ls
cd ~/.elixir-ls
mix deps.get
MIX_ENV=prod mix compile
MIX_ENV=prod mix elixir_ls.release2 -o release

The last command builds the executable language server to ~/.elixir-ls/release/, and that is the path we need to use in the coc.nvim configuration.

Step 2: Configure coc.nvim

Open your coc settings in Vim with :CocConfig and add:

{
  "elixir.pathToElixirLS": "~/.elixir-ls/release/language_server.sh"
}

Step 3: Install coc-elixir

In Vim, run:

:CocInstall coc-elixir

This installs the coc.nvim extension that communicates with ElixirLS.

Step 4: Verify

Open an Elixir file in your project. You should see:

• Autocomplete suggestions
• Inline diagnostics and warnings
• Go-to-definition working (:call CocAction('jumpDefinition'))

Understanding the .elixir_ls Directory

When you first open an Elixir project, ElixirLS creates a .elixir_ls/ directory and compiles your project. You might wonder why it doesn’t just use _build/.

ElixirLS maintains its own build for several reasons:

1. Avoids conflicts - Your _build/ uses your development environment. ElixirLS compiles separately so running mix test doesn’t invalidate the language server’s build.

2. Different compile options - ElixirLS uses flags that capture additional metadata for IDE features. These would slow down normal development builds.

3. Dialyzer PLT files - ElixirLS caches Dialyzer’s Persistent Lookup Table here. Building PLTs is slow, so caching them per-project saves time.

4. Independence - If your _build/ breaks, ElixirLS keeps working.

Consider adding .elixir_ls/ to your global gitignore:

echo ".elixir_ls/" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

Troubleshooting

If ElixirLS behaves unexpectedly, the simplest fix is to delete its cache and restart:

rm -rf .elixir_ls/

Then in Vim:

:CocRestart

ElixirLS automatically recreates the directory and recompiles when it restarts.

Common reasons to clear the cache:

• Upgraded Elixir or Erlang versions
• Dialyzer giving stale warnings
• Language server stuck or unresponsive
• Dependency changes not being picked up

As a developer, I use the terminal extensively and often SSH into remote machines for management tasks. When I connect via SSH, iTerm2 automatically updates both the window and tab titles to something like user@machine-ip:directory-name, which provides helpful context about where I’m working. The problem? These titles don’t automatically revert when I disconnect, leaving me with stale information in my terminal tabs.

For years, I had no idea what was happening under the hood, let alone how to fix it. My workaround was crude but effective: close the tab and open a new one. Eventually, I got fed up and decided to take some actions. After some research, I added this mysterious snippet to my .zshrc:

precmd() {
  # sets the tab title to current dir
  echo -ne "\e]1;${PWD##*/}\a"
}

I’ll be honest—I didn’t fully understand how it worked, but it did the job. This function “forced” my tab title to always display the current directory name, even after disconnecting from SSH sessions.

Later, I discovered Prezto, a configuration framework for Zsh that includes a handy set-tab-title function. This gave me more flexible control over tab titles, so I happily retired my hacky precmd solution.

You might have noticed that the window title remained untouched throughout this journey. It simply wasn’t annoying enough to warrant investigation—until Claude Code came along.

Since its public launch in February, Claude Code has become my go-to tool for AI-assisted coding. Like SSH, it helpfully sets custom tab and window titles to show what it’s working on. Also like SSH, these titles stick around after Claude Code exits, cluttering my terminal with outdated information like “Building Feature X…” or “Optimising test performance…” long after those tasks completed.

Since I was using Claude Code across multiple projects every day, these stale titles were starting to get on my nerves and that was the final straw. It was time to properly understand how terminal titles work and build a comprehensive solution.

Understanding Terminal Titles in iTerm2

Before diving into solutions, let’s understand what we’re dealing with. iTerm2 (and most terminal emulators) recognize two distinct title types:

1. Tab Title - Displayed on the individual tab
2. Window Title - Shown in the center of the window’s title bar

These titles are controlled through ANSI escape sequences - special character combinations that terminals interpret as commands rather than text to display.

The Magic Behind Terminal Titles

Here’s how escape sequences work for setting titles:

# Set window title only (shows in title bar)
echo -ne "\033]2;Your Window Title\007"

# Set tab title only (shows in tab)
echo -ne "\033]1;Your Tab Title\007"

# Set both window and tab to the same title
echo -ne "\033]0;Your Title\007"

The cryptic \033] starts the escape sequence, the number (0, 1, or 2) specifies which title to set, and \007 (the bell character) ends it.

Quick note on escape characters: You might see these written as \e (instead of \033) and \a (instead of \007) in some scripts—they’re equivalent, just different representations of the same ASCII characters. I’m using the octal format (\033 and \007) here for maximum compatibility across different shells and systems.

Simple, right? Well, not exactly intuitive and quite cumbersome to use, which is why we’re building a better interface.

The Solution: A Simple Title Manager

Let’s create a user-friendly function that makes title management a breeze. Add this to your ~/.zshrc (or ~/.bashrc for Bash users):

# Terminal title management functions
terminal_titles() {
    case "$1" in
        window)
            echo -ne "\033]2;$2\007"
            ;;
        tab)
            echo -ne "\033]1;$2\007"
            ;;
        both)
            echo -ne "\033]0;$2\007"
            ;;
        help)
            echo "Usage: terminal_titles [window|tab|both|reset|help] [title]"
            echo "  window [title] - Set window title only"
            echo "  tab [title]    - Set tab title only"
            echo "  both [title]   - Set both window and tab to same title"
            echo "  reset          - Reset to default titles"
            echo "  help           - Show this help message"
            echo "  (no args)      - Same as reset"
            ;;
        reset|"")
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
            ;;
        *)
            echo "Unknown command: $1"
            echo "Use 'terminal_titles help' for usage"
            ;;
    esac
}

# Alias for convenience
alias tt='terminal_titles'

How to Use It

Now you have a simple tt command at your disposal:

# Reset titles to show current directory info
tt

# Set a custom window title
tt window "Development Server"

# Set a custom tab title
tt tab "logs"

# Set both to the same title
tt both "Project X"

# Get help
tt help

The default behavior (tt with no arguments) resets your titles to something useful:

• Window title: Full path of current directory (with ~ for home)
• Tab title: Just the current folder name

For example, if you’re in /Users/you/projects/awesome-app, the window shows ~/projects/awesome-app and the tab shows awesome-app.

Conclusion

After years of closing and reopening tabs to clear stale SSH titles, and more recently dealing with Claude Code’s persistent status messages, I finally have a solution that just works. The tt command is now muscle memory—quick to type, easy to remember, and does exactly what I need.

The beauty of this solution is its simplicity. No complex configurations, no heavyweight terminal managers—just a few lines of shell script that give you complete control. Whether you’re jumping between SSH sessions, running Claude Code throughout the day, or just want cleaner tab organization, you now have the tools to keep your terminal titles under control.

Happy terminal customizing! 🚀

Note: After building this solution, I discovered that Prezto actually has a set-window-title command hiding alongside the set-tab-title function I’d been using for years. Had I found it earlier, this entire journey into the depths of ANSI escape sequences might never have happened. But you know what? I’m okay with missing it. Sometimes the scenic route teaches you more than the shortcut ever could, and now I truly understand what’s happening under the hood rather than just blindly using a command.

Appendix: Auto-Reset with Smart Persistence

If you want titles to automatically reset after commands like Claude Code exit, but keep your manually-set titles, here’s an enhanced version with intelligent auto-reset. This adds more complexity but offers finer control:

# Terminal title management functions with smart auto-reset
terminal_titles() {
    case "$1" in
        window)
            echo -ne "\033]2;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        tab)
            echo -ne "\033]1;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        both)
            echo -ne "\033]0;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        help)
            echo "Usage: terminal_titles [window|tab|both|reset|auto|help] [title]"
            echo "  window [title] - Set window title only"
            echo "  tab [title]    - Set tab title only"
            echo "  both [title]   - Set both window and tab to same title"
            echo "  reset          - Reset to default titles"
            echo "  auto           - Enable auto-reset after commands"
            echo "  help           - Show this help message"
            echo "  (no args)      - Same as reset"
            ;;
        auto)
            unset TERMINAL_TITLE_MANUAL
            terminal_titles reset
            echo "Auto-reset enabled"
            ;;
        reset|"")
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
            unset TERMINAL_TITLE_MANUAL
            ;;
        *)
            echo "Unknown command: $1"
            echo "Use 'terminal_titles help' for usage"
            ;;
    esac
}

# Alias for convenience
alias tt='terminal_titles'

# Auto-reset after commands ONLY if not manually set (for zsh)
if [[ -n "$ZSH_VERSION" ]]; then
    precmd() {
        # Only reset if titles weren't manually set
        if [[ -z "$TERMINAL_TITLE_MANUAL" ]]; then
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
        fi
    }
fi

This enhanced version adds:

• Smart persistence: Manually-set titles survive command execution
• Auto-reset mode: Titles automatically update after commands (when not manually set)
• Flexible control: Switch between manual and automatic modes with tt auto

The Smart Workflow

1. Normal operation: Titles auto-update to show your current directory
2. Set custom title: tt tab "server logs" - This persists across commands
3. Return to auto-mode: tt auto or tt reset

A couple of weeks ago, we attempted to upgrade our Erlang/OTP version from 24 to 25.3.2.16, which was the latest release at the time. Unfortunately, shortly after the new release containing this change was deployed to production, our Customer Service team reported that a specific payment feature had stopped working. In fact, they noticed that we had stopped receiving this type of payment almost immediately after the new release hit production. The timing was too suspiciously close for this to be a coincidence.

The Investigation

When investigating this issue, I had no idea what the cause was, but I did have significant time pressure due to the nature of the problem—payments not being processed is always urgent!

First thing I did was to understand where the failure was happening and managed to replicate it in my local environment. Next, I methodically went through the all the changes in this release, reverting suspicious-looking changes one by one. Surprisingly, none of our actual code changes was the culprit.

The OTP version upgrade had seemed like one of the most innocent changes with regard to the payment issue we were facing. However, after exhausting other possibilities, I tested against OTP 24 since the OTP upgrade was a relatively major change in the same release. I was quite shocked to discover that the new version of OTP was indeed the guilty party.

The (Partial) Solution

Since I’m not an expert on certificate validation in Erlang, the error message we got when making requests to the bank looks cryptic:

TLS :client: In state :wait_cert_cr at ssl_handshake.erl:2123 generated CLIENT ALERT: Fatal - Unsupported Certificate
 - {:key_usage_mismatch,
 { {:Extension, {2, 5, 29, 15}, true, [:keyCertSign, :cRLSign]},
  {:Extension, {2, 5, 29, 37}, false,
   [{1, 3, 6, 1, 5, 5, 7, 3, 2}, {1, 3, 6, 1, 5, 5, 7, 3, 1}]}}}

But armed with this error message, I was able to find a Github issue in the official OTP repository about the same problem. Apparently other developers making HTTP requests with Erlang/Elixir had encountered the same issue.

Thanks to Ingela Andin, the maintainer, and the community’s efforts, a fix had already been released for OTP 26 and 27. But unfortunately for us, there was an impression that OTP 25 wasn’t affected, so no fix had been done for it. Given our urgent situation, we decided to revert back to OTP 24 to restore payment processing as quickly as possible.

It’s worth noting that after I reported that OTP 25 was indeed affected by the same issue, Ingela responded quickly and worked on backporting the fix. A new patch version with the fix was released about two weeks ago, clearing our path to safely upgrading to OTP 25.

Now that we had a solution, I wanted to better understand what caused the problem in the first place.

Understanding Digital Certificates

To understand the bug, we need a quick primer on SSL/TLS certificates: digital certificates are like digital ID cards that websites use to prove their identity. Each certificate contains:

• The website’s public key
• Information about the website (domain name, etc.)
• Information about how the certificate can be used
• A signature from a trusted Certificate Authority (CA)

Certificates have “extensions” that specify what they can be used for. Two important ones are:

• Key Usage (KU): Broadly defines what the certificate’s key can do (sign things, encrypt things, etc.)
• Extended Key Usage (EKU): More specifically defines the certificate’s purpose (web server authentication, email, etc.)

The Bug in OTP

The bug occurred because recent versions of OTP was enforcing a rule that wasn’t actually specified in the certificate standards (RFC 5280).

In simple terms:

• The certificates from certain CAs like Entrust had a flag set indicating they could sign other certificates (keyCertSign)
• They also had flags set saying they could be used for web server authentication
• OTP thought these two purposes were contradictory and rejected the certificate

It’s like if you’re qualified as both a teacher and a restaurant chef, but then a bureaucrat refused to accept because “you can’t possibly do both these unrelated jobs.” In reality, of course, there’s no reason someone couldn’t be qualified for both roles independently.

And same goes for digital certificates. The certificate standard (RFC 5280) allows certificates to serve multiple purposes simultaneously, but OTP’s new validation logic was too restrictive.

For those interested in further technical details, there are extensive discussions in the Github issue and here is the PR that fixed it.

Takeaways

A few interesting lessons from this experience:

1. Hidden Complexity: Even mature, well-tested software like Erlang/OTP can have subtle bugs in complex areas like SSL/TLS.
2. Implementation vs. Specification: The bug wasn’t a coding error but an overly strict interpretation of a technical standard.
3. Community Matters: Thanks to the Erlang community for identifying and fixing this issue very quickly.

Summary

In this post, we started with an unexpected payment issue in production from upgrading the OTP version to 25. After identifying the new OTP version as the culprit, we had to revert back to OTP 24.

We also dove into understanding how the bug happened, which was essentially an overly strict interpretation of certificate standards. Thanks to the responsive Erlang community and OTP maintainers, a fix was backported to OTP 25, resolving the bug.

For me this was quite an interesting experience, because the overwhelming majority of bugs we face as developers are introduced by ourselves in the application layer. Sometimes we do encounter bugs in the library or framework that we use, but that’s pretty rare. It is ultra rare to face a bug in the underlying programming language. In fact, this was the very first one I had in my whole career as a developer, and I’ve been doing this for almost 20 years.

In the production configuration files of this project, we have environment variable names interpolated in strings as follows:

# config/prod.exs
config :my_app, MyApp.Repo,
  hostname: "${DATABASE_HOSTNAME}",
  username: "${DATABASE_USERNAME}",
  ...

Clearly this approach wouldn’t work for the :dev environment, where we would typically see something like this:

# config/dev.exs
config :my_app, MyApp.Repo,
  hostname: System.get_env("DATABASE_HOSTNAME"),
  username: System.get_env("DATABASE_USERNAME"),
  ...

However, I also knew that the interpolation syntax did work for us in production. This made me curious: How exactly does this work? It was time for some investigation.

The How

After consulting with our old friend Google and chatting with our new friend GPT-4, I learnt that this peculiar method of setting configuration values from environment variables is facilitated by Distillery, the tool we use for building releases.

For this functionality to be enabled, the environment variable REPLACE_OS_VARS must be set to true. And then Distillery would replace environment variables with their actual values upon encountering interpolation syntax, such as "${DATABASE_USERNAME}", in the configuration files.

As a matter of fact, when it comes to handling application configuration, Distillery supports more than simple variable interpolation. It also supports Config Providers, which are custom modules capable of dynamically generating configuration at the start of your application. For further details, please refer to the relevant section in Distillery documentation.

The Why

While it’s enlightening to learn how it works, I kept wondering: why does Distillery offer support for both interpolation and Config Providers? Isn’t System.get_env good enough for this purpose? As it turns out, although System.get_env is quite effective for the :dev environment, it can be inadequate for the production environment in many cases.

To grasp this, we need to take a step back and have a quick review of how Elixir the language works. Elixir is a compiled language. When you execute mix compile, the Elixir compiler transforms your project into Erlang bytecode. This bytecode then runs on the Erlang Virtual Machine, commonly known as Bogdan/Björn’s Erlang Abstract Machine (BEAM).

The configuration files and code that are outside of function bodies within a module are evaluated at compile-time. Thus, if you use System.get_env("DATABASE_HOSTNAME") within a configuration file, it’s evaluated during the compilation process. This means the value of the environment variable DATABASE_HOSTNAME is then captured and embedded in the application as a static value.

For production configurations, the goal is generally to dynamically capture runtime environment variables, rather than to embedding those from the build server as static values. Apparently using System.get_env wouldn’t achieve this purpose.

That is precisely why Distillery supports both the interpolation syntax and Config Providers, enabling dynamic configuration value setting from the runtime environment of the application.

It’s noteworthy that with version 1.9, Elixir introduced built-in support for releases as well, which includes a novel approach to runtime configuration. This was achieved through the introduction of a new configuration file config/releases.exs, which is executed every time a release starts. Then in Elixir 1.11, another configuration file config/runtime.exs was introduced, which is essentially a superior version of config/releases.exs. For more details on these developments, please consult to the relevant documentation.

Summary

In this post, I shared my initial confusion about the interpolation syntax "${DATABASE_HOSTNAME}" in our production configuration files, followed by an exploration into understanding how it works and why is it necessary for runtime configuration. As always, my aim is to provide a reference for my further self and perhaps assist others along their journey.

  type StringOrNumber = string | number

Here the StringOrNumber type can be either string or number as expected. The member types do not have to be primitive types and they can be custom types as well.

When dealing with union types, before we can apply operations or functions that are specific to one member type, we would need to figure out which member type we have and that’s called type narrowing.

There are many ways to narrow the type, but in this post I specifically want to cover the syntax for creating a custom function to do type narrowing. I found myself referring back to the “Using type predicates” section on the Narrowing page in Typescript documentation, so I figure it might be a good idea to make it slightly easier to find and potentially easier to remember by writing a post about it.

Let’s say we want to create a type narrowing function for the StringOrNumber type above, it would look like this:

function isString(input: StringOrNumber): input is string {
  return typeof input === 'string'
}

Here, input is string is called a type predicate and it is the return type of the isString function. In the function body, it needs to return a boolean value: true means input is the expected type and false means it is not. The function’s logic can be as complex as it needs to be. As long as it returns a boolean value in the end, it’ll work fine as a type narrowing function or say a type guard.

In this example, returning true means input is a string, otherwise it’s a number, considering it can only be either a string or a number.

We can use it like the following:

// assuming we have a function that returns a string or a number
let a: StringOrNumber = getStringOrNumber()

if (isString(a)) {
  a.length
} else {
  a + 3
}

Of course, this is just a contrived example to demonstrate the correct syntax. In a real world application, we would most likely just do typeof input === 'string' instead of creating a function to do it.

One more thing worth noting is that when we create a custom type guard, Typescript would treat us as adults and completely trust that it will do the right thing. For example, we can define a nonsensical type guard like this:

function isString(input: StringOrNumber): input is string {
  return typeof input === 'number'
}

And Typescript would happily accept it and gives no compiler error or warning, but since it’s narrowing the type incorrectly, some runtime errors should be expected after using this type guard.

In this post, I briefly talked about what type narrowing is and then looked into how to define our own type guard. As usual, the hope is to help my future self and potentially be of service to other people who are starting their Typescript journey as well.

When trying to understand macros, I use the slightly different mental model: a macro is like a template with a name that can optionally have parameters; when the name is used, it’s substituted by the template with “values” of the arguments injected.

Sorry if it didn’t make it better. I’ll try to explain what do I mean by that. But let’s first review how C macros work.

C Macos

Before actually compiling a C program, the C compiler will use the C preprocessor to transform the program, which is also referred to as preprocessing. One of the things that happens in this preprocessing step is macro expansion.

In GNU’s online documentation for the C Preprocessor, a macro is defined as following:

A macro is a fragment of code which has been given a name. Whenever the name is used, it is replaced by the contents of the macro.

You can define a macro like this:

#define DOUBLE(x) (2 * x)

NOTE: by convention macro names in C use uppercase.

And then use it as below:

DOUBLE(5)

During preprocessing, the preprocessor will replace it with (2 * x). The compiler would just see (2 * x) as if you wrote it in stead of DOUBLE(5) in the first place.

So a macro in C allows us to define a fragment of code that can have parameters, and when it’s used the macro name would be replaced by the code fragment we defined with arguments interpolated.

It’s worth noting that since this happens before compilation, the program is still just a piece of text, so both arguments interpolation and macro expansion are just literal text substitution.

How does this relate to Elixir’s macros? Well macro expansion in Elixir is definitely not text substitution, but it’s still substitution, just happens at a higher level.

The Abstract Syntax Tree (AST)

Most programming languages have the Abstract Syntax Tree (AST), which is a tree structure the compiler builds from the source code before turning it into either machine code or byte code.

In most languages, the AST is not exposed to us developers and we can get our code working without worrying about the AST or even knowing about it.

In the case of Elixir, the compiler give us access to the AST. This comes with great power and allows us to do many things that aren’t possible in other languages, creating macros among them.

You can get the AST for a piece of code by using quote, for example:

iex(1)> quote do
...(1)> 1 + 2
...(1)> end
{:+, [context: Elixir, import: Kernel], [1, 2]}

This is probably the simplest form, but in general Elixir’s AST is represented as a three elements tuple. When the expression is more complex, its corresponding AST is usually deeply nested.

In Elixir, the AST is also known as quoted expressions.

For more details on working with quoted expressions, please refer to offical Quote and unquote guide.

Macros in Elixir

One thing to remember about macros in Elixir is that they receive AST as arguments and return AST.

You can define a macro with defmacro:

defmodule MyIf do
  defmacro if(condition, do: action) do
    quote do
      case unquote(condition) do
        x when x in [false, nil] -> nil
        _ -> unquote(action)
      end
    end
  end
end

Then you can use it by:

require MyIf

MyIf.if true, do: IO.puts("Hello world!")

# or

MyIf.if false, do: IO.puts("Will not print anything")

Mental models about Macros

Tree Metaphor

To understand how macros work in general, I often use the tree metaphor. The entire program is just a big tree containing data and expressions as nodes, some of which are macro usages. This is literally correct with Elixir, because the compiler do convert the program into a big abstract syntax tree in the form of a deeply nested three elements tuple.

Defining a macro is like creating a template in AST or say a sub-tree. If there are arguments, they can be injected to the sub-tree with unquote.

During macro expansion, the Elixir compiler will replace each macro usage node with the AST sub-tree returned by its macro definition with the arguments injected. Because macros can be used inside another macro, macro expansion will happen repeatedly until there are no more macros.

If we compare Elixir macros with C macros, we can see that they both offer a way to substitute an expression with a template. The difference is that in C we define the template as text and replaced as text, whereas in Elixir, the template is defined as a piece of AST and the substitution happens at the AST level as well.

Copy-Paste Metaphor

To figure out what a particular macro does, I usually think of it as copying what the macro definition has and pasting it where the macro is being used. For unquoted arguments, mentally replace them with the corresponding values passed in.

When the macro is more complex, this might not work, but it should still set one on the right path in understanding the macro.

Summary

Macros are hard and they can be daunting even for experienced developers.

In this short post, I tried to offer a different perspective in understanding macros in Elixir.

It would fantastic if this makes it slightly easier for someone to learn about macros.

If you’d like to learn more about Elixir macros, check out Saša Jurić’s great blog post series Understanding Elixir Macros and Chris Mccord’s book Metaprogramming Elixir.

The Pi-hole® is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.

Pi-hole is a great piece of software if you are interested in a bit more privacy and saving some bandwidth at the same time.

As its name suggests, it can obviously be installed on a Raspberry Pi, but apart from that it actually runs on other Linux hardware as well. As long as your device can run one of the Officially supported Operating Systems, you should be able to run Pi-hole on it.

While supporting other hardware definitely has its use cases, I consider Raspberry Pi to be the best choice for running Pi-hole in the home network, because of its low cost and very low power consumption.

I happen to have a Raspberry Pi Zero that’s been collecting dust since I bought it a few years ago, which is perfect for running Pi-hole.

Install OS on Raspberry Pi

Obviously we need to install an operating system on Raspberry Pi before we could do anything with it.

The recommended way of installing an operating system for Raspberry Pi is to use the Raspberry Pi Imager. You’ll need a computer with an micro SD card reader to install an OS image on your card.

I’m running it on macOS, but it supports Linux and Windows as well. Just make sure to download the correct version for your OS.

Click CHOOSE OS to choose from a list of options. I’d recommended just go with Raspberry Pi OS (32-bit), which is the first option, unless you have a specific purpose for the Pi and you know what you are doing.

Then click CHOOSE STORAGE to select the mounted micro SD card. Remember that the imager will erase the card first, so you’ll lost everything on the card. Make sure you’ve got backup for anything you still need on the card.

Lastly, click WRITE to install the selected OS on your card.

For most of the OS options, the imager will download the OS image while writing it to the micro SD card. If you have a slow Internet connect, you can also download the OS image separately from the Raspberry Pi OS download page and then choose Use custom for the OS option and select the downloaded .img file.

Advanced options for the imager

There is also an “Advanced” menu in the imager, which you can open with Ctrl-Shift-X. This menu allows you to perform tasks like enabling SSH and setting admin password. As described in the next section, we can do those with terminal commands too.

Setup Raspberry Pi

Since I find connecting a monitor, a keyboard and a mouse to the Raspberry Pi quite cumbersome, I’d like to setup a headless Raspberry Pi.

In order to achieve that, there are a couple more things to do before booting the Raspberry Pi: enable SSH access and allow auto WiFi connection.

Enable SSH access

On macOS, the SD card with Raspberry Pi OS image is usually mounted on /Volumes/boot.

We can enable SSH by creating an empty file named ssh in the root directory of the card:

cd /Volumes/boot
touch ssh

Auto WiFi connection

I’d also like the Pi to be able to connect to WiFi when it boots up.

In order to do that, create a text file named wpa_supplicant.conf with the following content:

country=<your-country-code>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
network={
    ssid="<your-wifi-ssid>"
    psk="<your-wifi-psk"
    key_mgmt=WPA-PSK
}

Obviously, fill in the ISO 3166 alpha-2 country code of your country, your WiFi SSID and PSK.

Then copy the file to the root directory of the SD card:

cp wpa_supplicant.conf /Volumes/boot

Note: if you are using an older Raspberry Pi (like my Pi Zero), it might not support 5GHz networks

Connect via SSH

After the two steps above, we can put the SD card in the Raspberry Pi and boot it up.

Once it’s up and running, we should be able to connect to it via SSH:

ssh pi@<ip_for_raspberry_pi>

The default password is raspberry.

Make sure to update the admin password with passed after logging in.

Fix locale

When you run commands on the Raspberry Pi, you may see warnings like this

-bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)

So you might want to fix the locale.

If you are comfortable with vi or nano, just edit /etc/locale.gen and uncomment the line starting with en_US.UTF-8.

Otherwise you can run the following command to do the same:

perl -pi -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen

Then run the following:

locale-gen en_US.UTF-8
update-locale en_US.UTF-8

After that, the annoying warnings should be gone.

Check out Jared Wolff’s post for more details on locale.

Install Pi-hole

Now the Raspberry Pi is in a reasonable state, we are ready to install Pi-hole.

The most convenient way to is to use the following command:

curl -sSL https://install.pi-hole.net | bash

The installation process is relatively straightforward. Just follow the prompts to get it done.

If you’d like to know what the installation script actually does, check out the source code basic-install.sh.

Take advantage of Pi-hole in the network

After Pi-hole is successfully installed, we still need to configure the router to use Pi-hole as the DNS server, which makes sure that all devices on the network will be protected automatically by Pi-hole.

If that’s not supported by your router or you only want certain devices to use Pi-hole, you can configure the DNS server on each device.

You might want to check out this comprehensive guide on the different options to configure Pi-hole as your DNS server.

Manage blocklists

Pi-hole comes with a default blocklist:

https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

Which is well maintained and provides good protection without breaking normal functionality in most cases. For many this might be enough, but if you have other requirements, such as blocking adult content or targeted ads, you can add custom blocklists for improved blocking capabilities.

Check out The Best PiHole Blocklists (2021) for some blocklist options and more importantly, what to think about when choosing a blocklist.

You can add/remove blocklists under Group Management -> Adlists in the Pi-hole admin interface. After making changes there, you’ll need to either run pihole -g in terminal or go to Tools -> Update Gravity and click the Update button.

Whitelist Youtube history and etc

With the default blocklist from Pi-hole, the only thing that no longer works for me is Youtube history on iOS devices.

Adding a domain to the whitelist would solve that:

pihole -w s.youtube.com

Or if you prefer the admin interface, you can add a domain in Whitelist.

If you find other sites or services not working properly after introducing Pi-hole, you might want to check out the Commonly Whitelisted Domains and potentially whitelist relevant domains.

Keep software up-to-date

Last but not least, keeping things up-to-date on the Raspberry Pi would be a good idea.

Since Raspberry Pi OS is based on Debian Linux, we can use apt for that:

sudo apt update
sudo apt full-upgrade

Also we can remove packages that are no longer required with:

sudo apt autoremove

Summary

In this post, I walked through how to install Raspberry Pi OS, setup headless Raspberry Pi, install Pi-hole, manage blocklists and etc.

As many of my other posts, the main purpose is to serve as a reference for my future self. But if someone else finds it helpful too, I’d be very glad :slightly_smiling_face: