And let’s say you’re using rspec-rails as your testing library.

And let’s say you’re writing system specs (RSpec’s wrapper around Rails system tests) to test how your Rails app works when you visit it in a browser and click around.

It’s important that, when those system specs run, your front-end assets have already been built, or the test will fail hard, with errors indicating that the assets are unavailable.

It’s also important that, when those system specs run, those front-end assets are up-to-date. propshaft will be looking for assets in app/assets/builds. If you haven’t built your front-end assets in a few days, maybe some of your source code has changed, and those built assets don’t include the latest changes. In this case, your tests may fail in confusing ways. propshaft is able to find and serve app/assets/builds/application.js but your test fails because the script is missing some critical new feature that was added this morning.

So how to avoid these annoying and confusing situations?

One factor is to consider how you’re running RSpec. Let’s think about the difference between these different ways to run an RSpec test suite:

$ bin/rspec
$ bin/rails spec

In the former, you’re using the RSpec CLI directly¹ and in the latter you’re using a rake task defined by the rspec-rails gem².

When you use the rake task (bin/rails spec), everything Just Works. You’ll notice that assets build automatically every single time you run it, so they’re always present and they’re always up-to-date. Here’s what’s happening:

1. The task is defined like this:

    RSpec::Core::RakeTask.new(spec: "spec:prepare")
   

   That is, the spec task (which is defined in rspec-core and which runs all the specs) depends on the spec:prepare task, which is defined just below.

2. The spec:prepare task invokes the test:prepare task，which is defined all the way back in Rails
3. The test:prepare task does… nothing at all! Per the source code, it is a “Placeholder task for other Railtie and plugins to enhance.”
4. jsbundling-rails and cssbundling-rails do exactly that. They enhance the test:prepare task so that whenever test:prepare runs, rake will also run the javascript:build and css:build tasks.

So that’s nice: everything is automatic and works as long as you run your RSpec test suite using the bin/rails spec task.

It kind of sucks that you need to rebuild all of your assets every time you run any test, but it works.

Now, what if you want to use the bin/rspec CLI to run your tests? There are a lot of reasons that you might want to do that:

1. It has a lot of useful flags for customizing its behavior and its output
2. You can run specific spec files by passing them as arguments

One option you have is to just remember to run bin/rails spec:prepare or bin/rails test:prepare before you run your tests, which will take care of it. Try very hard not to forget, or you may end up with confusing failures. Make sure to document this well for everyone else who works on this project to make sure other people know to do this too.

Another option is to make some kind of wrapper script. We can imagine something like a bin/prepare-and-rspec which looks like

#!/bin/sh

set -e

bin/rails test:prepare
bin/rspec "$@"

That way you can just run bin/prepare-and-rspec --format documentation spec/models/user_spec.rb and everything should Just Work. Of course, it still kind of sucks that you have to rebuild your assets every time you run a spec, even if nothing changed. And it’s still possible that teammates might not discover this script, and they’ll just keep using bin/rspec and hitting mysterious failures here and there.

Another option is to add some kind of an RSpec hook which takes care of building assets before the test suite:

RSpec.configure do |config|
  config.before(:suite) do
    system("bin/rails javascript:build", exception: true)
    system("bin/rails css:build", exception: true)
  end
end

This is a pretty good option! Now you can just use bin/rspec and trust that it will automatically build assets whenever you run specs.

Of course, it still sucks that you need to rebuild all of your assets every time you run any test.

And even worse: if you do happen to run bin/rails spec, now you’re rebuilding all of your assets twice, once from your custom hook and once from the test:prepare enhancements.

This is actually pretty close to where I’ve landed in my project. I’ve zhuzhed it up a little by adding some logic which tries to determine whether re-running is actually necessary:

class AutoCompileInTests
  def initialize(command:, inputs:, name:)
    @command = command
    @inputs = inputs
    @name = name
  end

  def run
    return if ENV["CI"]
    return if already_compiled?

    system(@command, exception: true)

    marker_file.write(cache_key)
  end

  def wait
    return if ENV["CI"]

    loop do
      return if already_compiled?

      sleep 1
    end
  end

  private

  def already_compiled?
    marker_file.exist? ? marker_file.read == cache_key : false
  end

  def marker_file
    Rails.root.join("tmp/cache/auto-compile-#{@name}")
  end

  def cache_key
    md5 = Digest::MD5.new
    @inputs
      .map { |input| Dir.glob(input) }
      .flatten
      .uniq
      .each do |path|
        pathname = Pathname.new(path)
        next if pathname.directory?

        md5.update pathname.read
      end

    md5.hexdigest
  end
end

RSpec.configure do |config|
  config.before(:suite) do
    tasks = [
      AutoCompileInTests.new(
        command: "bin/rails css:build",
        inputs: [
          ".node-version",
          "Gemfile.lock",
          "package-lock.json",
          "app/assets/stylesheets/**/*",
        ],
        name: "css"
      ),
      AutoCompileInTests.new(
        command: "bin/rails javascript:build",
        inputs: [
          ".node-version",
          "Gemfile.lock",
          "package-lock.json",
          "app/javascript/**/*"
        ],
        name: "javascript"
      )
    ]

    # if you aren't using parallel_tests, this can simply be
    # tasks.each(&:run)
    ParallelTests.first_process? ? tasks.each(&:run) : tasks.each(&:wait)
  end
end

The goal with this code is to list out the tasks that need to run at the top of the test suite. For each task, we give it a name, a command, and inputs. The inputs are all of the files that, if any of them change, we should rerun the task just to be safe. Then, we’ll make a hash of all of those inputs and write it to a temp file (./tmp/cache/auto-compile-css or ./tmp/cache/auto-compile-js) and we’ll run the command. The next time, we’ll recompute the hash and compare it to the tempfile; if it matches, no need to rebuild the assets. If you ever want to force the assets to rebuild, you can just remove those tempfiles by running rm tmp/cache/auto-compile-*.

If you’re using the terrific parallel_tests gem to run your tests in parallel, it’s important to only automatically build your assets in one of the parallel processes and not all of them. To achieve that, we can have the first process take on the job of building the assets, and have the other processes spin their wheels and wait for the build to finish before proceeding to running specs.

This is a bit of extra complexity, but I think it’s worth it if your assets are a bit slow to build.

Of course, it would be nice if all of this Just Worked out of the box, but I’m not sure exactly what that would look like.

Feel free to get in touch if you have ideas to improve this setup.

In March, I went to see Ragtime. Of course I turned off my iPhone at the start of the show. After, when I turned it back on, I found that it had decided to apply a software update. This happened to be the same day that iOS 26.4 was released, which included some security fixes.

To my surprise, in order to unlock my phone, I needed to connect to wi-fi, so it could “activate”. Uhh. Okay. Lincoln Center happened to have a public wi-fi network, so I tried connecting to that.

Then it told me that this iPhone is “Locked to Owner”, and that “Activation Lock prevents anyone who is not the owner from using this iPhone. To unlock this iPhone, enter the Apple Account and password that were used during setup.”

This is a reference to a feature called Activation Lock that I apparently have enabled.

In theory this is cool – if my phone is stolen, I like the idea of making it harder for the thief to get in to my phone. But why does it think my phone was stolen? I was just trying to be a conscientious theater-goer.

I have a problem now – I don’t have my Apple Account password memorized. I use a password manager to store all of my super strong, randomly-generated passwords. And my password manager is on my phone, which is locked.

Then I notice that there is an option to use a “passcode” instead of my Apple Account password. Oh okay great, I know that. I have a passphrase, not a passcode, but okay, let’s try it.

On that screen, I see “To unlock this iPhone, enter the passcode that was previously used on this device.”

What does that mean?

I try my current passphrase. Nope.

I try the passphrase I’m pretty sure I used before my current passphrase. Nope.

I try a passcode I think I might have used a few years ago before switching to a passphrase. Nope.

At this, I see a dialog indicating “Incorrect Passcode” and “A device passcode can no longer be used to activatet his device. The passcode was entered incorrectly too many times”. Oh okay.

So I turned my phone off and went home.

Thankfully I know how to get home from Manhattan to Brooklyn. Thankfully I wasn’t dependent on Apple Pay to tap in to the subway. Thankfully I didn’t need to call a taxi. Thankfully I didn’t need to contact anyone or be contacted by anyone urgently. Thankfully I had a paperback with me.

At home, I pulled up 1Password on my computer, looked up my Apple Account password, and unlocked my iPhone. Then I forgot all about it.

Until it happened again last night while I was seeing Schmigadoon!!

After the show when I turned my phone back on I saw that I had updated to 26.4.1 and I was locked out again.

This experience sucks.

The funny thing is that I love installing updates. There’s no need for them to wait to spring it on me unexpectedly when my phone is off. Just put a little red dot on the Settings app and I’ll happily install the update within hours. 26.4.1 was released like two weeks ago. Why wait until the worst possible moment?

The other funny thing is that 26.4.2 was released yesterday and it has security fixes. But they didn’t update me to that one, for reasons that are not at all clear to me.

I’m seeing another show in the next few weeks – feel free to place bets on whether I learn any lesson from this.

Maybe I should have compiled a few examples before writing this. I have one at the moment. Consider https://cursor.com/blog.

This is the blog for Cursor, which I understand to be a popular and influential fork of Visual Studio Code that adds lots of AI code generation features. I haven’t used it but I’ve heard that people like it.

They’re blogging about where they think things are going in the world of programming, which I’m interested in. But there’s no feed to subscribe to, so I’ll probably miss their future posts.

OK here’s one more: https://fabro.sh/blog – this is another AI tool, created by my old boss from Code Climate, Bryan Helmkamp. I’m curious about what he’s up to and where this will go, so I’d happily subscribe and hear future updates. But there’s no feed.

I have two theories on what might be happening here:

1. Skipping the RSS feed is a status symbol. A flex. They’re saying, “we don’t need one. We know that what we have to say is so obviously compelling that whenever we speak, our words will echo across the land across social media, coverage on other blogs and news aggregators, etc. We just can’t be bothered.”
2. They’re using AI to build their websites, and whatever prompt they’re using doesn’t mention an RSS feed, so the generated website doesn’t have one. Back when people were using off the shelf software like Wordpress to power their blogs, they’d have RSS feeds because all Wordpress websites automatically get one.

Whatever the reason: it sucks. Add an RSS feed.

This is a thing that other blogs have, and I thought it would be fun to participate. You can see a list of all kinds of “slash pages” here: https://slashpages.net/#uses. I’m not making all of those but I’ll make this one.

I previously blogged about this once before, in 2017: the hardware and software I use (2017). It’s been long enough that plenty has changed, but it’s fun to see what hasn’t. I’m still using the same monitor, Fastmail, NearlyFreeSpeech.net. This site is still built with Jekyll and hosted on GitHub pages.

I’ll try to remember to update my uses page once or twice a year going forward.

Let’s say you use it to run tests on pull requests before merging them. The action will check oout the code from your branch, and then run the tests.

What exactly is it checking out?

You might assume that it basically just checks out your branch. Or maybe it checks out the head commit on your branch?

Nope.

It checks out our pull request’s “merge ref”.

The pull request merge ref is sort of like a branch which GitHub creates automatically for all of your pull requests. It represents what you’d get if you were to merge your PR into the target branch.

For example if we consider this diagram¹:

  main    my-great-feature-branch
          *
          *
      *   *
      *   *
      * *
      *
      *
      *
      *
      * oldest commit

This shows a feature branch with a handful of new commits that are not represented on main. It also shows that, since branching off of main, a few other commits have been made to the main branch which are not represented in the feature branch.

When I open a pull request to merge my great feature branch into main, GitHub automatically creates a third branch which has all of the commits from both branches. And that’s what the actions/checkout action checks out.

This is kind of helpful: if your tests pass, you can feel pretty confident that you aren’t going to break the main branch if you merge it in.²

This is also kind of confusing: if your tests fail, and you try to run the tests locally to see exactly why they’re failing, you might find that they pass locally, and now you need to figure out why exactly things are behaving differently locally and in CI. If you find yourself in this scenario, the answer is simple: just rebase your branch on top of main (or merge main into your branch) and then the test should start failing locally too, and you can debug it.

It is possible to configure actions/checkout to just check out the head commit on your pull request’s branch. This is a scenario they document in their README: https://github.com/actions/checkout/tree/v6.0.2?tab=readme-ov-file#checkout-pull-request-head-commit-instead-of-merge-commit. Doing that would be less surprising, perhaps.

I’ll close by saying this: Music just sounds better when you’re not streaming it. Not only because the audio quality is often literally higher, but because you’re forging a connection with what you’re hearing that’s strengthened by your choices, your commitment, your active participation—and, if you bought it at a shop or the merch table at a show, by the lasting imprint of those in-person interactions, however brief they might have been. Spotify can do a lot of things, but it can’t compete with that.

I switched to using Doppler and started buying mp3s again. Mostly on Bandcamp, occasionally on iTunes. I used Syncthing to keep my library in sync across my personal Mac Studio, my personal Thinkpad running Linux, and my work MacBook Pro. I tried at times to listen to radio, but there are so many ads that it’s not really possible to have on while working without constantly feeling annoyed, so I mostly gave up on that. Instead I mostly stuck to my mp3s and YouTube.

(On Linux, which I used a bit this year, I used the GNOME Music app although to be honest I didn’t listen to music on my Linux laptop much this year.)

Being off streaming, my listening habits changed. I did end up spending more time with fewer artists, and I did appreciate that.

So here’s what I listened to this year, in no particular order. Mostly 2025 releases but not all.

• Oklou - choke enough – my introduction was this spellbinding Tiny Desk performance which I watched many times. The record is more electronic. I like these songs in either mode.
• Chloe Qisha - Modern Romance EP – and also her other EP, although that was released in 2024. Witty, droll pop music to listen to on a loop. When I said I didn’t miss you, I lied, I’m sorry.
• The Clash - Train in Vain – this was on the soundtrack of Halt and Catch Fire, which I rewatched a good chunk of this year, and it’s just a perfect song
• Mk.gee - Are You Looking Up (Live) – a magical performance I first heard of him maybe this year or last year, who knows. This guy is so cool. It’s fun to watch him jam on his own, with Dijon, or with Bieber.
• Lady Gaga - Killah (Saturday Night Live/2025) – This whole Lady Gaga performance is so cool. The opening dance. The drumming. The scream. The costume change. Sick.
• JENNIE & Dua Lipa - Handlebars – this song has a very nice groove that I enjoy and the music video is worth watching jjust so you can try to help me understand what they were going for there. There’s just so much going on. The surreal disconnection between all of the images makes me wonder (like so many things did this year) if this was AI’s doing. I feel a little bit like the guy in Pete Holmes’s bit about the guy in the audience of the magic show confidently saying, “This is magnets”.
• Lizzy McAlpine - Staying (Live from The Greek Theatre, Los Angeles) – I found this performance (from an artist I’m not terribly familiar with) so lovely and confident. It begins with a lengthy piano prelude before layering in the vocals and the other instruments… And what a cool set! I wish I’d seen that show.
• Gregory Alan Isakov - The Trapeze Swinger (Iron & Wine cover) – an interpretation of an old favorite Iron & Wine song which feels to me like a whole new song. This one draws my ear to the rhythm of the vocal melody.
• ROSÉ & PSY - APT. (live from 싸이흠뻑쇼 SUMMERSWAG 2025) – I think history has vindicated Psy as the coolest guy in the world. The arc of history is long but it bends toward justice.
• mewithoutYou - Live (vol. Two) – despite ending their run a few years ago, mewithoutYou (who are very special to me) are still producing some aftershocks, in the form of a planned trilogy of live albums, the second volume of which came out this year. They’re very cool artifacts – they insist on not labeling the tracks in the mp3 metadata because they want the experience to be like attending a live show, where you don’t know which song is coming up next. The recordings all come from different shows and are mixed together seamlessly. They sound so good. A bit of on-stage patter is preserved. I was very happy to see Stereogum write a love letter to them this year, and also see Lucy Dacus bring Aaron out for a cameo on her tour. He may be a retired rock star who seems pretty happy working as a professor of anthropology these days¹² but I can still daydream that he’ll pop back up with a solo album at some point…
• Tim Armstrong - Take This City – This song is from 2007 and I listened to it then and somehow stumbled back upon it this year. What a gem. This is the frontman from Rancid and he is chilling out here. This is the mood I am trying to inhabit.
• Moving Mountains - Pruning of the Lower Limbs kind of out of nowhere, hometown heroes Moving Mountains came back online with a smooth, moody album that feels more grown up³ and laid back than some of their earlier, angstier stuff. This is the album I put on in the subway with my Apple earpods to set the mood for getting around, unhurried, thoughtful, while reading a book.
• Sara Bareilles and Rufus Wainwright Perform “She Used to Be Mine” – this song, from the musical Waitress, was written by Bareilles, who originated the part. Here she is performing it as a duet with a male vocalist, which seems counter-intuitive and very unexpected to me. But Christ is it pretty! What a wonderful interpretation. Bareilles has sung this song so many times, but it feels like Wainwright pushes her to an even more tender place here somehow…
• Bear vs. Shark - Out Loud Hey Hey – BVS has been “my favorite band” for twenty years now and I still listen to them regularly. They went on tour this year, and I saw them twice in the UK in March. This track has emerged as a new favorite this year. I just love how it has two moments where the guitars drop out, seemingly to give the drummer a moment to strut his stuff, and then when they do come back it’s in this very percussive mode, as if the guitars are inspired to be more like drums. Such a potent dose of mania in less than two minutes. Perfect song. Perfect band, still. I should’ve traveled to see more of their shows.
• Jane Wickline Gives Dating Advice – Comedy music lives. I am rooting for Wickline to thrive on SNL, I think she’s very funny in an internet sort of way.
• Wet Leg - mangetout in the Live Lounge – I should probably actually buy this album because the YouTube algorithm knows I’m going to click on the thumbnails for this band. They’re so strange and fun. They feel like they exist in some other world of their own creation.
• Geese - Au Pays du Cocaine – The song of the year, easily. This band got a lot of buzz and at first I thought they were weird and pretentious and dumb and I got fully converted, they’re actually weird and pretentious and smart. This is the kind of song that makes me want to go watch all of the amateur covers from all the weirdo sweeties who also felt deeply stirred by this perfect gem of a tune. It’s the kind of song that makes me want to record my own amateur cover.
• The Weakerthans - Sun In An Empty Room – this is the perfect theme song to Heavyweight, which came back from hiatus this year. It’s so imbued with that association that I don’t know that I would have even noticed this song if I’d heard it out of context, but it’s Pavlovian for me now. I hear this and I feel wistful.
• Christopher Owens - This Is My Guitar (Live Acoustic Performance) – I hadn’t thought of this guy for many years, but this crossed my transom and hit me like a hammer. That guy! What happened to him? I don’t really know. I haven’t looked into it and won’t speculate. But this is a really beautiful tune that suggests it hasn’t always been easy.
• KiiiKiii - Debut Song – I am not the biggest kpop fan but I loved this article about what the industry is churning out these days and how it compares to the recent past. I watched a bunch of the linked songs, and my favorite was easily Crayon Pop’s FM which is a crazy contrast with this KiiiKiii tune.
• McKenzie Kurtz - It Hit Me Like a Hammer – This, from the short-lived Huey Lewis and the News jukebox musical, is Kurtz’s big number. I love McKenzie Kurtz. She’s great. She can do anything, including make me like Huey Lewis and the News.
• Maggie Rogers - In The Living Room – This single came out after her 2024 album. Maybe it didn’t fit there, because it’s this exuberant, bombastic thing, while somehow also a wistful, domestic lament. I love it. She almost sounds out of breath because she’s giving it her all, which is saying a lot.
• Audrey Hobert - Who’s the Clown? – This is another pop album I listened to on a loop this year. She’s got such a gift for understated comedy and overstated dancing. Small phrases will catch me by surprise, like in Shooting Star when she sings in her friends voice, telling her “Girl, that’s not a shooting star” and then replies in her own, “I’m sorry, my bad, I thought that it was”. I like songwriters who are conversational and wordy and somehow rigorous all at once.
• Jacob Collier Improvises the National Symphony Orchestra – I usually find Collier fairly mechanical and dull, but seeing this former child prodigy be basically a kid in a candy store really enchanted and impressed me. I’m of course jealous.
• Frank Watkinson - I Miss You – An old many mournfully playing Blink-182’s loveliest tune. Achingly beautiful stuff.
• Wednesday - Bull Believer – Seeing them play this live a few months ago boiled my brain and restarted it. It’s so loud and so committed and so powerful. I also loved the lead single from their new album from this year, Elderberry Wine, which hardly sounds like the same band, but they’ve got range, and which Wednesday you’re gonna get depends on the day of the week.
• Dan Hardin - Romeo and Juliet – This was uploaded to YouTube in 2007 and it looks like it. This is a Dire Straits cover and it’s one of my favorite covers. A few years ago I thought of it and tried to find it and was sad to learn that Hardin had made all of his videos private to protest YouTube running ads on them (I think?). I happened to think of it again today and was delighted to see that he’d made them public again. What a perfect song. A Christmas miracle. This time I downloaded it. It’s only 10mb.

This is a very random assortment of recommendations but I hope you found something to like here. Those are the highlights. Bon voyage, 2025.

Like everyone else, I’ve used Google a ton and it’s been very useful. In recent years, I’ve felt kind of like Google isn’t serving my needs as much. I’m not a big fan of the AI widgets at the top of the search results (see this recent article, Google Is Burying the Web Alive from John Herrman). And I find that when I visit the Google homepage on my phone, it’s popping up clickbait articles under the search bar that are uncannily good at grabbing my attention, and suddenly I’m forgetting what I was going to search for in the first place.

I tried out DuckDuckGo for a few months and it’s a fine replacement, but they’re also popping up a little AI widget all the time and you can ask it to go away but then it just comes back after a while and that kind of rubs me the wrong way too.

I just tried out Kagi for a month. It’s a paid search engine, and it’s $10 per month, but you only get 300 searches per month, and I apparently use more than that, and I can’t quite bring myself to pay $25 a month for this, so I think I’m out.

If there’s no search engine that I’m excited to use, maybe I should use no search engine? It’s a bit of a hard sell, given that I clearly love to search (I used up my 300 Kagi searches in 20 days!). It’s muscle memory: just write something and hit enter, over and over.

But I know how to break muscle memory. Recall my steam locomotive post about how to break command line habits. All I need to do is find a way to see a six second animation of a train whenever I try to google something, and then I’ll stop googling things.

Thankfully, most browsers have a way to specify a custom search engine, and I know how to make websites, so I can just make my own search engine, and configure my browser to use that. And I can make that search engine display a six second animation of a train, or whatever else I would like.

Despite being motivated here by some antipathy for AI insofar as it is not what I am looking for when I am just trying to Google something, and even though I do worry that it is fairly likely to put me out of work in the next few years or at the very least make my job different in ways that mostly suck, I can’t help but be curious about how other people are using it, and so I decided to try to build this search engine site by vibe coding. I’ve had fairly limited success with vibe coding but this seemed pretty doable. I was inspired by a recent blog post and video from Mary Rose Cook demonstrating how she approaches “AI-Augmented Programming” which gave me some insight into how to actually use these things effectively, which doesn’t come super naturally to me.

Here’s what I came up with:

https://maxjacobson.github.io/search-engine/ (source) (GitHub Copilot wrote 100% of this code and I didn’t read any of it)

No matter what you search, you see a spinner for two seconds and then it says “There are zero results”. Lol.

I think this should be basically fine. I can bookmark websites that I know are useful, and I can go to them, and I can use the search functions built in to those sites. That’s the plan.

This feels likely to flop, but I think it’ll be interesting. Will report back

After ten years of using zsh as my shell, I’ve recently switched to fish.

I’d been aware of fish for a while, and had even kicked its tires once or twice before, but the impression I’d gotten was that it was super opinionated and “quirky”, and that rubbed me the wrong way. It turns out that’s sort of true, and nowadays I think that’s actually a great thing to be.

I was inspired by these recent blog posts to take another look:

• Reasons I still love the fish shell by Julia Evans
• Fish 4.0: The Fish Of Theseus from the fish blog

Evans’ post is a good introduction to what makes fish an appealing shell from a longtime user. It covers some of the great functionality that exists outside of the box. Some of it has been ported to zsh, like zsh-users/zsh-syntax-highlighting which adds “Fish shell like syntax highlighting for Zsh” and zsh-users/zsh-autosuggestions which adds “Fish-like autosuggestions for zsh”. Much of my zsh configuration, it turns out, was making zsh work more like fish works out of the box. Hmm!

The announcement post details their ambitious Rust rewrite which was recently completed. The writing in that post is kind of great. It’s funny and clear. There’s compelling storytelling alongside a bunch of technical context. Reading it, I felt like I could happily read changelog updates from these maintainers. It also made me realize that I’ve never read a single piece of writing from the zsh maintainers and don’t even know where I’d go to find it.

Upon a bit of digging, I did find the zsh news page, which has not been updated since May 2022 and the zsh release notes page page which has plenty of detail about each release, but does not feel like it was written for a general audience. Overall the zsh web presence is fairly confusing. There is a zsh.org but it hardly has any information on it. Instead it refers the hapless reader to zsh.sourceforge.io/. Plenty of information exists there, but the whole thing feels to me like it’s covered in cobwebs. Some ambitious web designer looking for a cool project should absolutely volunteer to do some spring cleaning on that site.

Switching

I didn’t think I was in the market for a new shell, but I got such a good vibe from the writing in that announcement post that I decided to try it out.

Actually switching to fish is fairly straightforward on macOS:

1. Install the shell brew install fish
   • As of this writing, that Rust rewrite is still in beta, so this will install the 3.x release. Honestly, don’t worry about it. I’ve tried both and can’t tell the difference. If you do want to join me in running the beta you can instead run brew install fish-shell/fish-beta-4/fish
2. Confirm where the fish binary is on the system: which fish, which prints out /opt/homebrew/bin/fish for me
3. Add that binary to the list of allowed shells: sudo vim /etc/shells and then add /opt/homebrew/bin/fish to the list
4. Change the default shell to fish: chsh -s /opt/homebrew/bin/fish
   • Note: no sudo needed on this one. If you do use sudo, you’ll change the default shell for your sudo user (super user?), not your regular user
5. Open a new terminal, and hopefully you’ll see that your shell is now fish. It prints a greeting by default.
   • Note: sometimes I need to log out and log back in after changing shells with chsh, and other times not. I’m not sure why. If the change doesn’t take effect, you can try that.

Next up was porting my zsh shell configuration to fish configuration. I was starting with a few files:

• ~/.zshrc – 197 lines (my general user configuration)
• ~/.zshenv – 1 line (setting up cargo)
• ~/.zprofile – 1 line (setting up homebrew)

Porting this code meant answering a few questions:

1. where does this go?
2. how do I rewrite this from the zsh scripting language to the fish scripting language?

Thankfully, fish’s docs are fantastic. Let me count the ways:

1. there is a search function
2. each page has a table of contents to make it easily navigable
3. there are lots of examples

Configuration

I found this doc that answered the question of “where does this configuration go?”: https://fishshell.com/docs/current/index.html#configuration.

Some things I learned about where configuration goes:

• I can put my general user configuration in ~/.config/fish/config.fish
• I can also, optionally, organize my configuration into various files in ~/.config/fish/conf.d/ which fish will also load
• The ~/.config/fish/conf.d files get loaded first, and they get loaded in alphabetical order, so if I want homebrew’s setup to happen earlier (so later configuration scripts can assume that homebrew-installed programs are available to use) I might want to put that in a file like ~/.config/fish/conf.d/0_homebrew.fish.
• In zsh I needed to worry about what was the difference between ~/.zshrc and ~/.zprofile and ~/.zshenv and never quite could remember. Similarly when I used bash and couldn’t remember what was the difference between ~/.bashrc and ~/.bash_profile. With fish I don’t need to worry about this. All of the config files are always laoded. Within those files, I am encouraged to define conditional logic if something only pertains to login shells or interactive shells.
• There is a way to manage configuration in a web UI but you don’t have to use that if you don’t want to
• Instead of putting helper functions into ~/.config/fish/config.fish (which does work) you are encouraged to instead define them in ~/.config/fish/name_of_function.fish. That way, the function doesn’t get loaded until you actually call it the first time, which speeds up your shell initialization. It also means you can add a new function there and it’s immediately available to already-running fish sessions without needing to reload any configuration.
• prompt configuration goes in ~/.config/fish/functions/fish_prompt.fish. To define a prompt you just define that function. A little more on this below.
• Because I’m a very cool minimalist, I can turn off the fish greeting by running set --universal fish_greeting.

Syntax

And I found this doc that answered the question of “how do I do all the basic programming stuff in fish?”: https://fishshell.com/docs/current/language.html

Some things I learned about the language:

• the syntax feels more modern than zsh or bash. For example, the keyword to end a conditional, loop, function, or block is end, just like in Ruby. No need to remember if it’s done or fi or esac or }.
• fish has a standard library of commands like path, math, string, and others. Their docs are great. It felt like they’d thought of everything and had elegant, non-hacky solutions to whatever I might need. And I can always access a local version by running, say help math to pop open the docs
• fish comes with a fish code formatter tool called fish_indent, which you can use to auto-format your fish code. It mostly does indenting, but it seems to do a little bit more than that, too. I enabled it as an ale fixer so it auto-formats on save when I edit fish files in vim. There’s also an ale fish linter which just checks for syntax errors as you go. Both very useful.
• the only way to create variables is with the set command. You can’t just write foo=bar or FOO=bar or export FOO=bar. This felt weird at first, but I quickly got used to it.

fish_prompt

I’m not a big fan of any of the prompts that fish offers out of the box. Since February 2021, I’ve been happily using pure and I was a little bit loathe to lose it. I decided to configure a fish prompt that looks a lot like pure, but which doesn’t have all of pure’s cool functionality. Here’s what I came up with in ~/.config/fish/functions/fish_prompt.fish:

function fish_prompt
    # Check if the last command succeeded so we can color the prompt red when it
    # did not succeed
    set --local last_status $status

    # Configure fish_git_prompt to show some more info
    set --global __fish_git_prompt_show_informative_status true
    set --global __fish_git_prompt_showdirtystate true
    set --global __fish_git_prompt_showuntrackedfiles true
    set --global __fish_git_prompt_showstashstate true
    set --global __fish_git_prompt_showcolorhints true

    # Configure fish_git_prompt symbols
    set --global __fish_git_prompt_char_stashstate "≡"
    set --global __fish_git_prompt_char_cleanstate ""

    # blank line before each prompt
    echo ""

    # print some info
    string join '' -- \
        (set_color blue) (prompt_pwd --full-length-dirs 2) (set_color normal) \
        (fish_git_prompt)

    # print the actual prompt
    if test "$last_status" -ne 0
        string join '' -- (set_color red) '❯ '
    else
        string join '' -- (set_color magenta) '❯ '
    end
end

This looks a lot like pure, but it doesn’t try to match it 100%. It’s just nice for it to feel a bit familiar.

The main “cool functionality” that pure has, which this doesn’t, is that pure will auto-fetch git repositories for you. I have become somewhat dependent on this. I often hit enter a few times in a git repo just to see if the prompt changes, which might suggest that I need to pull down the latest changes. I considered updating this function to run git fetch when it sees a git repository. Once I started thinking about actually writing that, I felt kind of like that’s actually a crazy thing for a prompt to do, and maybe it’s been crazy that my prompt has been doing that for the last four years. I couldn’t bring myself to do it.

However… I learned that it’s possible to define fish functions which respond to events, and that fish emits an event whenever it is about to call the fish_prompt function. I added this function to ~/.config/fish/conf.d/autofetch.fish:

function autofetch --on-event fish_prompt --description 'Fetch on prompt'
    if test -f ".git/FETCH_HEAD"
        set --local mtime (path mtime --relative .git/FETCH_HEAD)
        set --local duration (math '10 * 60')

        if test "$mtime" -gt "$duration"
            git fetch --prune --prune-tags --quiet
        end
    end
end

This will autofetch, synchronously, if it determines that we haven’t fetched the repo in the last ten minutes. That’s not exactly what pure did, but in practice it’s good enough. I no longer hit enter a few times as a weird way to say “please fetch for me”. Occasionally my prompt hangs for a sec before rendering. Occasionally my prompt indicates that the remote has new commits I might want to pull down. When I’m not connected to the internet, this autofetch fails. It’s not perfect, but I think I overall do like it. And I like that it’s decoupled from the actual rendering of the prompt, so the prompt function can focus on the single responsibility of rendering a useful prompt.

And I love that this kind of thing is even possible and easy in fish to do. Callback functions! What is this, JavaScript?

(Additionally, pure achieves an impressive performance by rendering its git details asynchronously. In theory that’s very cool but in practice it hasn’t felt like an issue for me to have a synchronous prompt.)

Other events

If you want to write some function which runs each time you change directories, that’s also easy to do with events. In fact that’s how tools like fnm implement their functionality to switch node version when changing directories into a project that uses a particular version of node (via):

function _fnm_autoload_hook --on-variable PWD --description 'Change Node version on directory change'
    status --is-command-substitution; and return
    # command that activates the correct version of node
end

_fnm_autoload_hook

This defines a function, tells fish to call it whenever $PWD changes, and then calls the function once, to ensure it runs on shell initialization too.

That’s so elegant. I don’t know if I have a need for doing something like that just yet, but I like knowing I can if I need to.

Universal variables

One gotcha that really confused me was universal variables, a feature I haven’t seen in other shells before.

If you run:

set --universal foo bar

Then the $foo variable is sort of sticky. It exists in every active fish session, including future fish sessions. The value is persisted on disk, and fish references that file on disk to get the value. It’s possible to update the variable (set --universal foo baz) or remove it (set --erase foo). But just be aware, because it can be really confusing if you had a line like set -U foo bar in your ~/.config/fish/config.fish, and then you deleted that line, and the dang variable is still defined???

abbreviations

fish supports aliases just like zsh does. At first I ported over my various aliases and carried on happily. After continuing to poke around the fish docs, I came upon abbr, which manages fish abbreviations.

Previously I had this in my ~/.zshrc:

alias 'cat'='bat'

This is because I wanted to use the very nice sharkdp/bat instead of cat, but my muscle memory continued to keep typing cat anyway.

Now I have:

abbr --add cat bat

The behavior is pretty similar, in the sense that I type cat, and bat runs. The difference is that as soon as I type bat, and then hit space or enter, cat gets replaced with bat in my interactive shell. So I get to see what actually ran, instead of what I originally typed. And that’s what goes into your command history, too. It’s a subtle difference, but I appreciate it.

It’s also possible to define command abbreviations. So, for example, I have a handful of git aliases like git co being an alias for git checkout. Up until now, I’ve defined those aliases in my ~/.gitconfig. But now I’ve migrated all of those to be fish command abbreviations. For example:

abbr --command git co checkout

Now when I type git co, that automatically expands to git checkout.

It’s even possible to create abbreviations that call a function to programmatically determine what the abbreviation should expand into. For example, I have this:

function __fish_t_command
    set --local name (path basename $PWD)
    echo "tmux new-session -A -s $name"
end
abbr --add --function __fish_t_command t

Now when I type t in a project repo, it expands to tmux new-session -A -s seasoning, presuming I’m in a directory called “seasoning”.

(Astute Hardscrabble readers might notice that I’ve given up the over-engineered tmux helpers described in October 2023)

I think this expansion is just better than aliases. Once the command has expanded, tab completion works perfectly, for example.

custom completions

OK speaking of tab completions, one last cool thing before I ship this brain dump of a post.

One of the helper functions I ported from my old zsh configuration was this helper script:

# Clone repos from GitHub.
#
# Usage: clone maxjacobson/film_snob
#
# Inspired by https://github.com/pbrisbin/dotfiles/blob/632ab65643eac277c77c18a2587fec17fd1acac3/zshrc#L19-L28
function clone () {
  case "$1" in
    */*)
      target="$HOME/src/gh/$1"

      if [ -d "$target" ]; then
        echo "already exists"
        cd "$target"
      else
        mkdir -p "$target"
        gh repo clone "$1" "$target"
        cd "$target"
      fi

      ;;
    *)
      echo "Bad input"
      ;;
  esac
}

That became this fish function in ~/.config/fish/functions/clone.fish:

# Clone repos from GitHub.
#
# Usage: clone maxjacobson/film_snob
#
# Inspired by https://github.com/pbrisbin/dotfiles/blob/632ab65643eac277c77c18a2587fec17fd1acac3/zshrc#L19-L28
function clone --description "Clone a repository from GitHub"
    switch "$argv"
        case "*/*"
            set --local target "$HOME/src/gh/$argv"
            if test -d "$target"
                echo "already exists"
                cd "$target"
            else
                mkdir -p "$target"
                gh repo clone "$argv" "$target"
                cd "$target"
            end
        case '*'
            echo "Bad input"
    end
end

Very similar, although there’s definitely less syntactical cruft.

I thought it might be fun to try adding a tab completion to this function that will tab complete the repositories that are available to clone. Everything in fish has great tab completion, but my helper function did not. By default it suggested the files in the current working directory as tab completion candidates, which was annoying.

I learned that it’s possible to configure a command’s tab completions by adding a file in ~/.config/fish/completions/clone.fish

For example you can add this just to tell it not to tab complete filenames:

complete --command clone --no-files

The docs for the complete command have tons of examples. They also encourage you to poke around the completions that come with fish. I found a big trove of them in /opt/homebrew/Cellar/fish/4.0b1/share/fish/completions after checking the directoreis in fish_complete_path. There’s lots of inspiration there.

Ultimately here’s what I came up with:

complete --command clone --no-files

function __fish_clone_repo_pattern
    set --local subpattern "[a-zA-Z0-9\-\_\.]+"
    echo "($subpattern)/?($subpattern)?"
end

# clone foo/<tab>
# clone foo/bar<tab>
# clone foo<tab>
function __fish_clone_should_search
    string match \
        --quiet \
        --regex (__fish_clone_repo_pattern) \
        (commandline --current-token)
end

# look up a particular owner's repos
function __fish_clone_search_results
    set --local groups (
      string match \
          --groups-only \
          --regex (__fish_clone_repo_pattern) \
          (commandline --current-token)
    )
    gh search repos \
        --owner="$groups[1]" \
        --json fullName \
        --jq '.[].fullName' \
        "$groups[2]"
end

# clone foo/<tab>
# will search GitHub for foo's repos and offer them as tab completions
complete \
    --command clone \
    --condition __fish_clone_should_search \
    --arguments '(__fish_clone_search_results)'

There’s a lot going on there, but the upshot is that when I type clone maxjacobson<tab>, fish will ask GitHub what repos are owned by maxjacobson and offer them as tab-completion suggestions.And if I type rails/action<tab>, it tab completes just the repos owned by rails that have action in the name.

Programming in fish is fun. I know it’s possible to do this kind of thing in zsh too, but I never would have attempted it.

Conclusion

I have been having a lot of fun with fish! Perhaps more posts to come as I continue poking at things.

It’s easy enough, you just need something like this in the <head>:

<meta property="og:image" content="https://www.hardscrabble.net/img/preview/2024-10-03-colors.png">

Because I use Jekyll to generate my blog, it wasn’t too hard to add a little conditional logic that includes that meta element if a post specifies a preview image filename in its front matter.

But it’s sort of annoying to have to prepare an image whenever you want to blog something. I don’t necessarily have time for all that.

Then, yesterday, I was poking around on Bluesky and saw this post:

I'm starting my 2024 #blogvent series where I post a blog a day in December! Blogvent day 1 is about fighting spam in your open source repos: cassidoo.co/post/oss-int...

[image or embed]

— Cassidy (@cassidoo.co) December 1, 2024 at 4:07 PM

And I got so jealous of how nice and clean that preview image is, and I had a few thoughts:

• Sigh I should blog more
• Dang can you imagine blogging that much?
• No, I mean, it would be so annoying to generate all those preview images
• Wait, how did she manage to auto-generate the preview images with text for each blog post??? That’s so cool!!!

I saw that her blog post is open source and I tracked down the lines of code, which look sort of like this:

---
const { title, description, image = "/home-blog-card.png" } = Astro.props;
---

<head>
  <meta property="og:image" content={new URL(image, Astro.url)} />
</head>

I sat and stared at that for several minutes, trying to puzzle out how it works. I’ve never used Astro, but it seems very powerful. I look at the docs.

Eventually I realized that actually it’s just a static image, and it isn’t dynamically changing the text for each blog post. I went back to her page and scrolled down past several links, and I saw that they all have the same text.

Lol.

But hey, I thought, maybe it is possible to generate custom images with text in them? And if it is, maybe it is possible to hook that into the jekyll build process?

And indeed it is. And I’ve done a somewhat basic version of that. And here’s how you can do that too.

First, create a plugin by creating a file called _plugins/opengraph.rb. Ruby files in the _plugins folder are loaded during the build process.

Within that plugin, register some jekyll hooks:

Jekyll::Hooks.register :posts, :pre_render do |post|
  unless post.data["preview_image"]
    preview = GeneratePreview.new(post)
    preview.write
    post.merge_data!({"preview_image" => preview.path }, source: "opengraph plugin")
  end
end

Jekyll::Hooks.register :site, :after_init do
  FileUtils.mkdir_p "tmp/img/preview"
end

Jekyll::Hooks.register :site, :post_write do
  Dir.glob("tmp/img/preview/*").each do |path|
    FileUtils.cp path, "_site/img/preview"
  end
end

The idea here is that for any post that doesn’t already have a preview image specified in the front matter, we’ll

• generate a preview image and write it to a folder
• modify the in-memory post object to know that it has a preview image with a particular filename. Because this is a :pre_render hook, the HTML for that post has not yet been written to disk, so it’s not too late to modify its metadata

And then, after the whole site has been written, copy all of those generated image files into place.

In this design, I don’t need to commit all of the generated files to the repository, I just generate them at build time. I need to regenerate them each time I deploy. This is a bit slow and ineffecient. I might decide to just commit them down the line.

The actual image generation code is sort of hacky. It’s a bit of ruby glue code that shells out to the venerable imagemagick CLI tool. It executes commands like this:

magick \
    -background "#f2d8b2" \
    -font "Helvetica" \
    -fill "#248165" \
    -size 1200x630 \
    -gravity SouthWest \
    "caption:The\ easiest\ way\ to\ indent\ paragraphs\ online,\ not\ that\ you\ necessarily\ should" \
    tmp/img/preview/2012-03-21-indenting-paragraphs-online.png

Which produces images like this:

Kind of obnoxious right? A little brat maybe? You tell me.

Getting this to run in GitHub Actions presented a few challenges. The ubuntu-latest machine where the builds run had imagemagick installed, but it was imagemagick 6, not 7. sudo apt-get install -y imagemagick just complained that hey, it’s already installed baby, nothing for me to do. But I had gotten all of this working with imagemagick 7 and I wasn’t about to redo anything.

Once I figured out how to install imagemagick 7, I had the next issue, which was that no fonts were installed on the machine, at least as far as imagemagick could tell. After installing the gsfonts package, it could see some fonts, but only the off brand, Linux versions of them. By running magick -list font in the CI context, I could see what those were. Eventually I worked out that something called Nimbus-Sans-L is basically knockoff Helvetica, which was what I had randomly picked locally. Great. Close enough. Perhaps you can tell but I have never really been a Font Guy. But I wanted this to work in both contexts, locally and in GitHub Actions. To work around that, I added some conditional logic to the ruby script to default the font to Helvetica, but allow overriding it via an environment variable.

And with that… everything was working, and I went to bed, criminally late, having forgotten what I originally had been planning to blog about. I remembered over lunch today and finished that post. And now here’s this.

Here’s the commit with all of the code, if you’re curious. It kind of works.

Here’s the verse (emphasis mine):

Sorry girls

But he could be criminal, some sort of psychopath

Who escaped from an institution

Somewhere where they don’t have girls

He could have masterminded some way to find me

He could be colorblind

How untrustworthy is that?

He could be less than kind

The context here is that Dawn is single and hesitant about putting herself out there. Most of all she’s afraid of being hurt, and the joke of the song is that she can’t quite admit that fact, and she chooses instead to enumerate all of her other excuses for not going on a date: minor infractions like calling the waiter by his first name or eating Oreos wrong, for example. It’s a breathless and very funny stream of consciousness. Ha ha, right?

But hold on, what’s her problem with colorblind people? How is it untrustworthy to be colorblind? I love this song, but I always trip over that line. In addition to being a bit ableist, it’s also such a non sequitor.

I’m reminded of the classic 2008 parody of Deep Blue Something’s Breakfast at Tiffany’s from the sketch comedy group Olde English:

That’s me right now.

Dawn’s characterization is probably strengthened by her being a little bit shitty about this. She’s such a sweet character that for her to be randomly biased against a protected group is funny, in a dark way. In the chorus, she asks, “What if when he knows me, he’s only disappointed?” The audience is inclined to love and root for Dawn, but in order for the song to resonate, she needs to show some human flaws.