posts on olafalders.com

Can Others Explain My Work Without Me?

Thu, 15 Jan 2026 00:00:00 +0000

I’ve recently found the time to revisit a passion project. The app has a number of moving parts and I was struggling to distill it down to an elevator pitch. I’m not actually pitching anything to anyone, but it seemed like a worthwhile exercise to try to summarize this thing that I’m building in a way that someone who doesn’t care how it works would understand.

I got started by using claude and the brainstorming skill that the superpowers plugin provides. That allowed me to get a clear definition of the problem I was trying to solve, an honest list of what the app currently does and a succinct summary of what makes it unique. Armed with this knowledge, I was already better able to describe the problem that I was solving and the solution which I was providing. Then I stumbled across a blog post that Anil Dash had just published. In it he describes a framework for thinking about the things you communicate, so that when you do share a message it becomes something that other people can repeat accurately and without difficulty. To quote the premise:

They have to be able to talk about us without us. What this phrase means, in its simplest form, is that you have to tell a story so clear, so concise, so memorable and evocative that people can repeat it for you even after you’ve left the room. And the people who hear it need to be able to do this the first time they hear the story. Whether it’s the idea behind a new product, the core promise of a political campaign, or the basic takeaway from a persuasive essay (guess what the point of this one is!) — not only do you have to explain your idea and make your case, you have to be teaching your listener how to do the same thing for themselves.

— Anil Dash, They have to be able to talk about us without us

“Microphone” by drestwn is licensed under CC BY 2.0.

This sounded like what I was trying to do, but it’s even more ambitious in its scope. I liked it. A lot. I wanted to try it out, but since I’m lazy, I wanted to see if I could use AI to help. Using the skill creation skill that superpowers provides, it took just a few minutes to turn a blog post into a reusable skill. I simply told Claude where to find the post and it did the rest. I tried the skill, loved the result, and I was off to the races. After test driving the skill on my passion project, I reached out to Anil to see if it was ok to (ab)use his content in this way. He graciously consented.

After trying the skill out for a few other things, I realized that packaging it as a plugin would make for the most convenient way for others to try it out as well. I asked Claude to create a plugin from the skill and that also took just a few minutes. You can find the plugin at https://github.com/oalders/talk-about-us. For a quick start, if you have claude installed, enter:

claude plugin marketplace add oalders/talk-about-us &&
claude plugin install talk-about-us@talk-about-us

(The repository contains a “skill” which is not specific to Claude. Check the README for instructions on how to use this with other AI clients).

This new skill will then be available to audit your content based on the principles in Anil’s post. Enough talk. Let’s see it in action. We are going to demonstrate this skill by seeing if one of my other passion projects, PrettyGoodPing, is doing a good job of communicating to the world what it does. I give you exhibit A. We’ll start with a screenshot of the site because (spoiler alert), the audit came back with so many issues that I’m going to need to rework the front page. I’ll show you the before:

If you want to try this at home, paste the following into Claude Code after you have installed the plugin:

Use the talk about us test to audit the content on the front page of https://www.prettygoodping.com/

You may see something like the following:

Content Summary

The front page presents PrettyGoodPing as a monitoring dashboard for web developers, focusing on SSL/TLS certificates, domain expiry, server ping, and uptime checks. The messaging is technical and feature-focused.

❌ 1. The Absence Test: FAIL

“Can someone authentically explain this when I’m not there?”

Current messaging:

“Monitor SSL/TLS & Domain Expiry, Uptime, and Server Ping”

“PrettyGoodPing [Beta] is a configurable dashboard for web developers”

Issues:

Heavy jargon: “TLS/SSL,” “domain registrations,” “server uptime,” “URL availability”

No one would naturally say this when recommending the service

Requires technical knowledge to understand what’s being offered

Very formal, not conversational

What someone might actually say: “It’s a tool that watches your website stuff and emails you before things break” - but the current copy doesn’t enable this kind of natural explanation.

❌ 2. The Distinctiveness Test: FAIL

“Does this say what only WE can say?”

Generic phrases that any competitor could use:

“configurable dashboard for web developers”

The feature list (SSL, domain, ping, uptime) is standard for monitoring tools

“optional email alerts” - not distinctive

What IS distinctive:

The name “PrettyGoodPing” has personality (modest, unpretentious)

Specific limits (25 certs, 5 domains) are concrete

“Built with Perl” goes against the grain

Problem: The distinctive personality suggested by the name isn’t carried into the copy. The messaging could belong to any monitoring service.

❌ 3. The Emotional Resonance Test: FAIL

“Is this emotionally gripping or comprehensively technical?”

Current approach: Comprehensively technical

Lists features and limits without explaining why you should care

No connection to the pain point (expired certs breaking your site, surprise downtime)

No emotional benefit (peace of mind, sleeping soundly, avoiding embarrassment)

Missing the “what problem does this solve” narrative

Missed opportunities:

The anxiety of discovering an expired SSL cert at 3am

The relief of proactive monitoring

The embarrassment of users seeing security warnings

The simplicity of “set it and forget it”

❌ 4. The Values-First Test: FAIL

“Are values embedded in how people naturally discuss this?”

The name suggests values: “Pretty Good” implies modesty, pragmatism, honesty (not overpromising “amazing” or “ultimate” monitoring)

The copy suggests different values: Technical precision, comprehensiveness, feature completeness

Disconnect: The personality and values aren’t woven into the language. There’s an opportunity to embrace the “pretty good” ethos - reliable, unpretentious, does what it says on the tin.

Recommendations

Lead with the problem/emotion, not features

❌ “Monitor SSL/TLS & Domain Expiry, Uptime, and Server Ping”

✅ “Never wake up to an expired SSL certificate again”

✅ “Your sites are being watched, so you can sleep”

Use natural, shareable language

❌ “configurable dashboard for web developers focused on monitoring TLS/SSL certificates”

✅ “A pretty good way to know when your website stuff is about to expire”

✅ “We’ll email you before your SSL certs, domains, or servers go sideways”

Embrace the personality from your name

The “PrettyGoodPing” name is brilliant - modest, honest, approachable. Carry that through:

“We’re not fancy, but we’re reliable”

“Does what it says, and does it pretty well”

“Simple monitoring that actually works”

Make it repeatable

Test: Can someone explain this at a meetup without sounding robotic?

❌ Current: “It’s a configurable dashboard for monitoring TLS/SSL certificates, domain registrations, server uptime, and URL availability”

✅ Better: “It watches your SSL certificates and domains, and emails you before they expire. Pretty straightforward.”

Show concrete value, not just features

Instead of listing emoji-decorated features, try:

“25 SSL certificates watched 24/7”

“Email alerts 10 days before disaster strikes”

“Because finding out your cert expired from an angry user email is the worst”

Specific Rewrite Suggestions

Hero Section (current):

“Monitor SSL/TLS & Domain Expiry, Uptime, and Server Ping” “PrettyGoodPing [Beta] is a configurable dashboard for web developers”

Hero Section (suggested):

“Sleep better knowing your sites are being watched” “We monitor your SSL certificates, domains, and uptime - and email you before things break. It’s pretty good at it.”

Feature Section (current):

🔒 TLS/SSL Cert Expiry

🌐 Domain Name Expiry

Feature Section (suggested):

🔒 Never miss an SSL renewal - We’ll bug you 10 days before it expires

🌐 Your domain won’t disappear - 3 weeks warning before expiry

Summary Score: 0/4 Tests Passed

The content is technically accurate but fails all four shareability tests. It’s jargon-heavy, generic, emotionally flat, and doesn’t embody the personality suggested by the excellent brand name.

Key insight: You have a distinctive, personable name (“PrettyGoodPing”) but corporate, generic copy. Let the personality shine through in the messaging.

I never considered my content to be corporate or generic, but here we are. I love that the skill pulls no punches. It reminds me of my first time attending my local masters swim club. The coach told me two things.

“Your stroke is killing me”
“Your stroke is a recipe for shoulder pain”

When I heard this feedback, I instantly knew I was at the right place. I wanted to become a better swimmer rather than swimming in compliments. My thoughts on the skill results are similar. What I need is an honest assessment rather than cheerleading.

(As an aside, the coach was correct and I have the scans of my rotator cuff to prove it.)

Now that I have feedback from the skill, I can work to address it. It’s tempting to have Claude do the work and pat yourself on the back, but I think you are going to get the best results with a collaborative approach. Allow Claude to point out the problems and make some suggestions. Then take the suggestions and make them your own. In my own work with this skill, I have taken the feedback to heart but also taken pains to update my content using my own words. I can still ask Claude to evaluate the new content, but the words I use will be my own. If I’m trying to say what truly only I can say, then it kind of makes sense for me to be the one to say it. Also, I write because it brings me joy. I’m not going to ask Claude to write my blog posts in the same way that I won’t ask it to solve my daily New York Times puzzles. I use AI to do the boring stuff, so that I can enjoy the good stuff.

Read on website

Oops! I just broke git-bisect

Mon, 05 Jan 2026 00:00:00 +0000

There are lots of opinions on how to group changes in your git history. I think most people would agree that a commit should contain a group of changes which logically belong together. However, deciding what merits being in the same commit could be a matter of contention. I try to follow one simple rule — do not break git-bisect.

According to the git-bisect documentation:

This command uses a binary search algorithm to find which commit in your project’s history introduced a bug. You use it by first telling it a “bad” commit that is known to contain the bug, and a “good” commit that is known to be before the bug was introduced. Then git bisect picks a commit between those two endpoints and asks you whether the selected commit is “good” or “bad”. It continues narrowing down the range until it finds the exact commit that introduced the change.

If I’m honest, I rarely actually use bisect, but I like this mental model because it forces me to ask myself if the code will still work as advertised when it’s checked out at this specific commit. If this is something that could get flagged by bisect as broken code, then I want to re-think what I’ve included in this set of changes.

It mostly comes down to “if a change breaks something, then the fix should also belong in the change”.

Compass by Walt Stoneburner is licensed under CC BY 2.0.

Why This Matters
#

Even if you never bisect, the knock-on effects of thinking about your commits in this way can be helpful both to you and others.

Code reviewers can follow your code without having to keep a mental checklist of “This change breaks ‘A’ – I’ll watch the subsequent commits to see where ‘A’ gets fixed again”
Future debugging becomes easier because you can see all relevant changes in the same set
CI failures become harder to dismiss with “we were never expecting this commit to work 100%”
Your commit history becomes a provably linear set of working changes rather than an aspirational attempt at correctness

The Common Anti-Pattern
#

Let’s examine a common workflow for fixing a bug:

Write a test which demonstrates the bug (commit a)
Fix the bug (commit b)

The beauty of this approach is that you can demonstrate that feature x was broken at commit a, but is clearly fixed by commit b.

The problem is that you have now introduced a point in your history where things don’t work. Anyone who lands at this point in future will need to clarify if you have truly introduced a bug and whether that bug has been fixed in a subsequent commit. This slows down code exploration, possibly making a tedious task even more unpleasant. So, while the intent of this approach is clearly one of good faith, the side effects can be problematic.

For me, I might produce the two commits as part of my workflow, but I would squash them together before shipping my code for review. If you do want to have the two unique commits, I’d suggest wrapping the failing test in a SKIP or TODO or FIXME block or whatever your testing framework supports. Remove the skip/todo/fixme in commit b as a demonstration that your bug has been fixed. That makes your intentions clear while not introducing new test failures into the commit history.

One reason it’s important to regulate this yourself is that your CI may not catch the commit with the broken test. If you wait until you have commits A and B ready before you ship to CI, then your CI will likely test only the last commit rather than both. You’ll be blissfully unaware that you’ve broken git-bisect. Unless your code reviewer runs the tests on all of your commits, they’ll also be none the wiser.

Making Review Easier, Not Harder
#

Does this methodology make reviewing commits more difficult? I don’t think so. If all of the necessary changes are in the same commit, then there should be less cognitive load placed on the reviewer. However, this is not a rule, but rather an approach to consider. If you’re staring a monster commit in the face, do what you need to in order to untangle it. git-bisect may not be the hill you want to die on.

While this approach can certainly make for larger commits, hopefully you’re dealing with this via well commented code or well commented commit messages. If your code is self-documenting, then congratulations on being a mythical creature whose code requires no further explanation.

Even if you don’t buy into the whole git-bisect approach, this can still serve as a helpful way to think about your code. Keep the things together that are required to prevent new broken tests from being introduced.

There will be exceptions to this rule, of course. Maybe you are vendoring third-party dependencies. A massive update of node modules has broken one of your tests. Your changes are harder to spot in the thousands of lines of JSON changes. This might be one of those times where you have one commit consisting solely of npm updates and a following commit (or more) to fix breaking changes. I treat the git-bisect approach not as a rule, but as a guideline. Use it when it makes your code better, but not when it makes your code worse.

More posts about git

Read on website

On a Prettier PATH

Wed, 16 Jul 2025 00:00:00 +0000

Knowing about your ENV variables can be really helpful. Knowing how to make them more readable can be even more helpful. Today we are going to look at some strategies for making env variables (and $PATH in particular) easier to read and easier to reason about. We’ll also touch on how to install tools like ubi and is in GitHub CI and take a quick peek at how using $GITHUB_STEP_SUMMARY can provide a quality of life improvement for those of us looking at CI logs.

As I run through various scenarios, I will use a Docker container so that we have a minimal environment. My real life environment is way messier. I won’t burden you with that, so let’s see what the Docker env looks like by default:

The Default env
#

$ env
HOSTNAME=ada083235895
SHLVL=1
HOME=/root
GOTOOLCHAIN=local
TERM=xterm
PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
GOPATH=/go
PWD=/workspace
GOLANG_VERSION=1.24.4

I see a couple of problems. First off, it’s hard for me to see what I want when things aren’t sorted. Let’s sort our env.

The Sorted env
#

$ env | sort
GOLANG_VERSION=1.24.4
GOPATH=/go
GOTOOLCHAIN=local
HOME=/root
HOSTNAME=ada083235895
PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
PWD=/workspace
SHLVL=1
TERM=xterm

This is already better, but I have to say that the PATH is not easy to to read. I don’t want to spend a lot of time staring at it. Can we do better? Well, we can isolate the variable to start with.

The Split PATH
#

$ echo $PATH
/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

What if we could split on the colon? That would help.

$ echo $PATH | tr : '\n'
/go/bin
/usr/local/go/bin
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin

A pretty path

"Forrest H. Dutlinger Natural Area (Revisit) (2)" by Nicholas_T is licensed under CC BY 2.0 .

A Tabular env
#

Fortunately we’re getting somewhere. Unfortunately I’ve now run out of patience with shell scripting. It turns out that is has us covered, though. Let’s see the ENV in a tabular format.

$ is known summary var
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Name ┃ Value ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ GOLANG_VERSION ┃ 1.24.4 ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ GOPATH ┃ /go ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ GOTOOLCHAIN ┃ local ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ HOME ┃ /root ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ HOSTNAME ┃ ada083235895 ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ PATH ┃ /go/bin ┃
┃ ┃ /usr/local/go/bin ┃
┃ ┃ /usr/local/sbin ┃
┃ ┃ /usr/local/bin ┃
┃ ┃ /usr/sbin ┃
┃ ┃ /usr/bin ┃
┃ ┃ /sbin ┃
┃ ┃ /bin ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ PWD ┃ /workspace ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ SHLVL ┃ 1 ┃
┣━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━┫
┃ TERM ┃ xterm ┃
┗━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━┛

This feels like an improvement to me. We have a sortend ENV with aligned columns and our $PATH is split on newlines, making it easier to distinguish between similar paths like /usr/local/bin and /usr/local/sbin.

A JSON env
#

Maybe we want do do something programmatic with ENV or maybe the tabular layout does not look good in our terminal logging. We do have another option: JSON.

$ is known summary var --json
{
 "GOLANG_VERSION": "1.24.4",
 "GOPATH": "/go",
 "GOTOOLCHAIN": "local",
 "HOME": "/root",
 "HOSTNAME": "ada083235895",
 "PATH": [
 "/go/bin",
 "/usr/local/go/bin",
 "/usr/local/sbin",
 "/usr/local/bin",
 "/usr/sbin",
 "/usr/bin",
 "/sbin",
 "/bin"
 ],
 "PWD": "/workspace",
 "SHLVL": "1",
 "TERM": "xterm"
}

Cool! Now I can get the first item in my PATH via jq.

$ is known summary var --json | jq .PATH[0]
"/go/bin"

Logging env in CI via Markdown
#

I’d love to emit this in my CI logs so that I can get debugging info on my environment. Let’s install is into our container in GitHub Actions:

---
jobs:
 linux:
 runs-on: ubuntu-latest
 steps:
 - name: Install is
 uses: oalders/install-ubi-action@v0.0.6
 with:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 projects: oalders/is

 - name: Display summaries
 run: |
 is known summary os --md >> $GITHUB_STEP_SUMMARY
 is known summary var --md >> $GITHUB_STEP_SUMMARY

What happened?

We used oalders/install-ubi-action to install ubi, which is the “Universal Binary Installer”. ubi allows us to install is without needing to care about which release we need to download and install.
We installed is
We emitted a summary for the os and for the environment variables
The summary was added to the $GITHUB_STEP_SUMMARY environment variable
We used a flag which has just recently been added to is: --md

The --md flag allows us to emit data in a Markdown table format. Why would we want to do this? Well, it turns out that GitHub logs are not always easy to read, and they can be constrained by width. So, if you have some really long paths in your environment, tabular data becomes close to unreadable.

GitHub offers the $GITHUB_STEP_SUMMARY variable as a nice solution to this. If markdown ends up in this variable, it gets rendered in an HTML summary of that build step. This means you get way more flexibility in how the data is rendered. There’s also the bonus that you don’t have to scroll through giant log files to find it.

And our PATH looks great:

Also, I can now embed the table directly into this blog post without needing to do any manual conversion to Markdown.

is known summary var --md

Name	Value
GOLANG_VERSION	1.24.4
GOPATH	/go
GOTOOLCHAIN	local
HOME	/root
HOSTNAME	44db2d2f4c32
PATH	/go/bin /usr/local/go/bin /usr/local/sbin /usr/local/bin /usr/sbin /usr/bin /sbin /bin
PWD	/workspace
SHLVL	1
TERM	xterm

So Long!
#

I think I’m not quite done with adding new commands to is, but for today I’m done with writing about it. 😅

Read on website

How Many Versions of "X" Are in my $PATH?

Tue, 17 Jun 2025 00:00:00 +0000

Occasionally I run into a situation where I have more than one executable with the same name installed in my $PATH. This is to be expected, and it’s generally not a problem until the executables are not found in the correct order. And what is the correct order? Usually “correct” is whatever arbitrary order makes sense for the thing that I’m currently doing, but it generally means that I want the thing with the highest version number to be found first.

For instance, the bash that ships with macOS is pretty old, so I generally install whatever homebrew has available and I want to default to that in every case.

$ which -a bash
/opt/homebrew/bin/bash
/bin/bash

Now, if I want to know which version of each is currently installed, I just have to remember the correct incantation for bash. Is it?

bash version
bash -v
bash -V
exec bash --version
bash --version

It’s the last one (and also the next to last, which has some cleaner output). Probably the last would have been my first guess, but maybe not, depending on how much of a hurry I am in.

If I’m curious about which versions are actually installed, I just need to copy each path and run --version on it. That’s ok, but it’s a bit clumsy. I could also cobble together some command line magic, but now I’ve really become distracted from the task at hand. Since I have is: an inspector for your environment installed, this becomes a bit easier.

$ is there bash --all
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Path ┃ Version ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━┫
┃ /opt/homebrew/bin/bash ┃ 5.2.37 ┃
┃ /bin/bash ┃ 3.2.57 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━┛

What if I’d rather see it as JSON?

is there bash --all --json

[
 {
 "path": "/opt/homebrew/bin/bash",
 "version": "5.2.37"
 },
 {
 "path": "/bin/bash",
 "version": "3.2.57"
 }
]

Now I can use jq to get the version of the macOS installed executable.

$ is there bash --all --json | jq '.[1].version'
"3.2.57"

I don’t know offhand why I would want to do that, but the important thing is that I can.

"Numbers" by andymag is licensed under CC BY 2.0

It gets interesting with things I may have even more versions of. Maybe the latest version is not where I think it is:

$ is there perl --all
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Path ┃ Version ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━┫
┃ /Users/olaf/.plenv/shims/perl ┃ v5.40.0 ┃
┃ /opt/homebrew/bin/perl ┃ v5.40.2 ┃
┃ /usr/bin/perl ┃ v5.34.1 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━┛

Possibly this can help me find things that I no longer need. It looks like Mason has been managing my gopls install for a while. I can probably delete the first gopls in my $PATH.

$ is there gopls --all
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Path ┃ Version ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━┫
┃ /Users/olaf/go/bin/gopls ┃ 0.15.3 ┃
┃ /Users/olaf/.local/share/nvim/mason/bin/gopls ┃ 0.18.1 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━┛

Because I work with computers, my days are full of minutia that slow me down. Little quality of life improvements can go a long way towards removing these tiny roadblocks. is: an inspector for your environment may be helpful to you as well.

Read on website

The Great PTS CLI Throwdown

Tue, 03 Jun 2025 00:00:00 +0000

I have this kind of annual tradition at the Perl Toolchain Summit where, at some point in the weekend, I look over Paul Johnson’s shoulder and admire his terminal setup. He knows his way around tmux, neovim and lots of other tools. I make it a point to check in with him again before the weekend is over so that I can steal everything. By the time the weekend is over we are both gone and I haven’t had a chance to poach his setup. At some point afterwards I’ll share some tool in the Fediverse that I think is cool and Paul will inevitably point me at something newer, shinier and cooler.

This year the tables were turned and Paul came to me on the first day of PTS to chat CLI. We decided that we’d get a few of us together on the following morning and we’d trade secrets. What follows is the notes that I took.

Full disclosure: I don’t use AI to write the content of my blog posts, but in this case I did run my notes through claude.ai to add some summaries and links. Claude didn’t get everything, but it was very helpful and it sped things along. Since this is meant to be a cheat sheet rather than a piece of creative writing, I’m ok with using AI as a tool to help get the job done.

This year’s participants in our first (annual?) CLI throwdown were, in order of appearance:

Paul’s Picks
#

WezTerm
#

A GPU-accelerated cross-platform terminal emulator and multiplexer implemented in Rust. Features include native mouse support, scrollback, ligatures, and color emoji.

yazi
#

A blazingly fast terminal file manager written in Rust, based on asynchronous I/O. Features include full asynchronous support, built-in image viewing capabilities, code highlighting, and git integration.

tmux powerline
#

A tmux plugin giving you a hackable status bar with beautiful powerline segments. Implemented in bash, it provides customizable segments for displaying information like session details, music player status, battery, and more.

Tailscale
#

A zero-configuration VPN built on WireGuard protocol that creates a secure network between your devices. It simplifies secure connections by handling NAT traversal and provides easy access control.

Neovim plugins
#

git-signs
#

A Neovim plugin that shows Git changes directly in the buffer signcolumn. Features include per-line git blame, stage/unstage changes, and navigation between hunks of modifications.

SmoothCursor
#

A Neovim plugin that adds a sub-cursor to show scroll direction, making it easier to track cursor position when using commands like % or <c-f> and <c-b>.

which-key
#

A Neovim plugin that displays a popup showing keybindings as you type, helping users remember complex key combinations and commands. Works across various modes, including normal, insert, and visual.

nvim-cmp
#

A completion plugin for Neovim written in Lua. It provides a powerful and extensible completion experience with support for LSP, snippets, and custom sources.

magazine.nvim
#

An nvim-cmp beta fork.

PerlNavigator
#

A language server for Perl, providing features like code navigation, completion, and diagnostics.

treesitter
#

A Neovim plugin providing an interface for Tree-sitter, a parser generator tool that provides incremental parsing capabilities, enabling better syntax highlighting and text-objects.

avante
#

A Neovim plugin designed to emulate the behaviour of the Cursor AI IDE.

mcp hub
#

A Neovim plugin that integrates MCP (Model Context Protocol) servers into your workflow.

markview
#

A Neovim plugin for viewing and editing markdown files.

nvim-scrollbar
#

A customizable scrollbar for Neovim that can be integrated with other plugins to display git changes or diagnostics in the scrollbar.

zsh
#

An extended shell with improved completion, scripting capabilities, and plugins. It’s highly customizable and offers numerous features beyond the standard bash.

eza
#

A modern replacement for the ls command with more colorful and human-friendly output, including git integration for directories.

Raycast
#

A productivity tool for macOS that provides a quick launcher, extensible commands, and scriptable automation capabilities.

stats
#

A macOS system monitor in your menu bar that shows detailed system statistics like CPU usage, memory, network, and more.

Shawn’s Picks
#

aerospace
#

A tiled window manager for macOS that arranges windows automatically and provides keyboard shortcuts for window management.

git restore
#

A Git command to restore working tree files, allowing you to discard changes or restore files from a specific commit.

lazyvim
#

A Neovim configuration framework that provides a pre-configured and opinionated setup with various plugins and sensible defaults.

ctrl-a
#

A Vim/Neovim feature that allows auto-incrementing numbers in text.

tmux keybindings in WezTerm
#

Using tmux-like key mappings within the WezTerm terminal emulator for consistent workflow.

caps-lock ctrl + escape
#

A keyboard remapping that makes Caps Lock act as Control when held and Escape when tapped.

karabiner
#

A powerful keyboard customizer for macOS that allows complex remappings and custom modifications.

bat
#

A cat clone with syntax highlighting, git integration, and line numbers, making it easier to view file contents.

fish
#

A user-friendly command line shell with syntax highlighting, autosuggestions, and smart tab completions.

delta
#

A syntax-highlighting pager for git, diff, and grep output that improves readability of diffs.

spacer
#

A utility for adding visual separation or spacing in user interfaces.

atuin
#

A tool that provides a searchable history with context for your shell, syncing across multiple machines.

devbox
#

A command-line tool for creating isolated, reproducible development environments.

direnv
#

An environment switcher that automatically loads and unloads environment variables depending on the current directory.

WezTerm quick select
#

A feature in WezTerm that allows quick selection and copying of text patterns like URLs, paths, or IPs.

chezmoi
#

A dotfile manager that helps keep track and synchronize your dotfiles across multiple machines.

asciinema
#

A tool for recording and sharing terminal sessions with playback capabilities.

Mickey’s Picks
#

terminator
#

A terminal emulator that allows you to arrange multiple terminals in a grid-like structure, each with configurable options.

ctrl-s stop streaming output
#

A terminal shortcut that freezes the terminal output, which can be resumed with ctrl-q (software flow control). This feature can be disabled in the shell using stty -ixon

tmux-resurrect
#

A tmux plugin that allows saving and restoring tmux sessions across system restarts.

cd is an alias to pushd
#

A shell configuration where the cd command is aliased to pushd, maintaining a directory stack for easy navigation. Complemented with cd- aliased to popd.

zmv for mass renaming via regex
#

A (zsh) tool for batch renaming files using regular expressions.

pdftk
#

A command-line tool for manipulating PDF documents, including merging, splitting, and form filling.

fpp
#

Facebook Path Picker, a tool that helps you select files from command output for further operations.

highlight
#

A simple tool that adds colors to matched text input.

Some favorite git commands
#

git checkout -p
#

A Git command that allows interactive selection of hunks to check out, similar to git add -p but for discarding changes.

git rebase -i
#

Interactively manipulate (reword comments, reorder or squash) commits (that are ahead of upstream).

git grep -W
#

Match showing the function context (e.g. Perl sub).

git push origin HEAD
#

Push current local branch to remote.

git branch –merged | grep -v master | xargs –no-run-if-empty git branch -d
#

Remove merged branches from local directory (use an alias).

git clean -dfx
#

Clean working tree from all untracked files (I have it aliased to distclean in .gitconfig).

Julien’s Picks
#

tig
#

A text-mode interface for git that provides a visual interface for navigating commits, diffs, and branches.

Editor’s note: I have previously written about tig.

shutter
#

A feature-rich screenshot tool with editing capabilities, annotations, and various capture modes.

peek
#

Olaf’s Picks
#

Sketchybar
#

A highly customizable macOS status bar replacement that can display system information, application status, and custom scripts. I recently wrote about SketchyBar.

Hammerspoon
#

A tool for powerful automation of macOS, allowing you to write Lua scripts that hook into system events and perform complex tasks.

oh-my-posh
#

A prompt theme engine for any shell that provides a customizable and beautiful prompt with git status, execution time, and more.

Alfred
#

A productivity application for macOS that offers features like hotkeys, keywords, text expansion, and clipboard history.

clipboard
#

Alfred’s clipboard history feature that stores text, images, and files, making them accessible via keyboard shortcut.

alfred-metacpan
#

An Alfred workflow for searching the Comprehensive Perl Archive Network (CPAN).

Cloudflare tunnels
#

A service that creates secure connections between your local resources and the Cloudflare network, without exposing public IPs.

typos
#

A source code spell checker that helps catch typos in your code, comments, and documentation.

is
#

An inspector for your environment. I have written too much about is already.

debounce
#

Limit the rate at which a command can fire. I have written about debounce.

gh
#

GitHub’s official command line tool for interacting with GitHub repositories, issues, and pull requests directly from the terminal.

ot
#

A command line utility tool with specialized functionality. I have written an intro to Open::This and a vim integration guild. I should write up my neovim integration sometime.

ubi
#

A command line tool for installing universal binaries across different platforms.

precious
#

A linter and formatter harness.

git-absorb
#

A git command that automatically identifies and squashes fixup commits into their relevant commits.

gum
#

A tool for glamorous shell scripts, helping create interactive CLI components like inputs, prompts, and spinners.

tailspin
#

A log file highlighter that improves readability of log files in the terminal with color coding and formatting.

"File:Roppongi 3K 3K (Professional wrestling moves).jpg" by ゾーヒョー is licensed under CC BY-SA 4.0 .

Read on website

Battery Power-Ups: Enhancing SketchyBar with "is"

Wed, 28 May 2025 00:00:00 +0000

is: the new subcommands
#

In my unrelenting quest to make ~~useless~~ barely useful software I recently added three new battery-related subcommands to is: an inspector for your environment.

is battery
is known battery
is known summary battery

These subcommands are a thin wrapper around distatus/battery, but they follow the patterns of the other is subcommands.

$ is battery --help
Usage: is battery <attribute> <op> <val>

Check battery attributes. e.g. "is battery state eq charging"

Arguments:
 <attribute> [charge-rate|count|current-capacity|current-charge|design-capacity|design-voltage|last-full-capacity|state|voltage]
 <op> [eq|ne|gt|gte|in|like|lt|lte|unlike]
 <val>

They allow you to do things like:

$ is known battery state
discharging

and

$ is battery count gt 0 && echo "we have 🔋"
we have 🔋

and

$ is known summary battery
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Attribute ┃ Value ┃
┣━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━┫
┃ battery-number ┃ 1 ┃
┃ charge-rate ┃ 0 mW ┃
┃ count ┃ 1 ┃
┃ current-capacity ┃ 76750.899 mWh ┃
┃ current-charge ┃ 99 % ┃
┃ design-capacity ┃ 76498.56 mWh ┃
┃ design-voltage ┃ 13.281 mWh ┃
┃ last-full-capacity ┃ 77534.478 mWh ┃
┃ state ┃ discharging ┃
┃ voltage ┃ 13.281 V ┃
┗━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━┛

and

is known summary battery --json

{
 "state": "discharging",
 "battery-number": 1,
 "count": 1,
 "charge-rate": 0,
 "current-capacity": 76750.899,
 "current-charge": 99,
 "design-capacity": 76498.56,
 "design-voltage": 13.281,
 "last-full-capacity": 77534.478,
 "voltage": 13.281
}

Now that we have some new tools at our disposal, what can we do with them?

SketchyBar (Before)
#

I’ve recently replaced the default macOS menu bar with SketchyBar. One segment of the menu bar displays the current status of my battery (if one is installed). Let’s have a look at my current menu bar.

My Desktop
#

As expected, my desktop doesn’t display a battery status.

My Laptop
#

My laptop, which (fortunately) has a battery, does display a battery status. Here we see the menu with the power supply plugged in and with the power supply removed.

I don’t love the default macOS menu bar. SketchyBar gives me portable way to have the same configuration on the various Macs that I use from day to day. It is configured via a collection of scripts and it ships with some nice default plugins. It even runs on 2017 Macs, which is what I’m slinging for my personal needs. Let’s dive right in and see how this helps with getting a battery icon into the status bar.

I started with this SketchyBar config. It allows me to configure which segments I want to appear in my menu bar and since this is basically a bash script, I can dynamically configure the menu bar based on my environment.

I want to add the battery to the menu bar conditionally, since in 50% of the cases, I won’t be on a laptop. I didn’t have a great way to see if I was using a laptop, so initially I would manually touch $PLUGIN_DIR/.laptop on the machines where I wanted to display a battery status. That worked fine as a stopgap.

if [ -f "$PLUGIN_DIR/.laptop" ]; then
 sketchybar --add item battery right \
 --set battery update_freq=120 script="$PLUGIN_DIR/battery.sh" "${button[@]}" \
 --subscribe battery system_woke power_source_change
fi

SketchyBar menu items are not only configured via scripts, they can also be updated via scripts. I started out using this script to find the current available charge in the battery as well as the charging state (is it charging right now?) The code to get those values was as follows:

PERCENTAGE="$(pmset -g batt | grep -Eo "\d+%" | cut -d% -f1)"
CHARGING="$(pmset -g batt | grep 'AC Power')"

If I’m honest, I didn’t write that code and it doesn’t really excite me. It has the potential to be brittle. Also, don’t ask me to explain it.

SketchyBar (After)
#

After installing the latest version of is, I’m able to make this a little nicer by no longer relying on a special file to exist. Here’s a diff:

-if [ -f "$PLUGIN_DIR/.laptop" ]; then
+if is battery count gt 0; then

That leaves us with:

if is battery count gt 0; then
 sketchybar --add item battery right \
 --set battery update_freq=120 script="$PLUGIN_DIR/battery.sh" "${button[@]}" \
 --subscribe battery system_woke power_source_change
fi

For the battery script itself, I can clean that up a little with this diff:

-PERCENTAGE="$(pmset -g batt | grep -Eo "\d+%" | cut -d% -f1)"
-CHARGING="$(pmset -g batt | grep 'AC Power')"
+PERCENTAGE="$(is known battery current-charge --round)"

-if [[ "$CHARGING" != "" ]]; then
+if is battery state eq charging; then

The current charge that I get back via distatus/battery is sometimes a few percentage points off from what pmset reports back. I don’t know if macOS performs some kind of smoothing, but for my purposes I’m not too concerned. I mostly care if the battery is fully charged, almost empty or has a reasonable amount of time left on it. Everything else is not that important.

One other consideration is that SketchyBar is installed via homebrew and launched via brew services, which doesn’t have the same $PATH as my user environment. I ended up adding the path to my is installation in both of the SketchyBar files that I need to maintain for this:

PATH=~/local/bin:"$PATH"

Summary
#

That’s basically it. My SketchyBar config is in my dot-files repo. The new is subcommands are well documented via --help and the README. If you can’t remember all of the available battery attributes (and why would you) the new is known summary battery subcommand can be very handy.

If you don’t currently have a battery, it’s pretty succinct:

$ is known summary battery
┏━━━━━━━━━━━┳━━━━━━━┓
┃ Attribute ┃ Value ┃
┣━━━━━━━━━━━╋━━━━━━━┫
┃ count ┃ 0 ┃
┗━━━━━━━━━━━┻━━━━━━━┛

Otherwise it can be quite verbose.

$ is known summary battery
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Attribute ┃ Value ┃
┣━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━┫
┃ battery-number ┃ 1 ┃
┃ charge-rate ┃ 0 mW ┃
┃ count ┃ 1 ┃
┃ current-capacity ┃ 76750.899 mWh ┃
┃ current-charge ┃ 99 % ┃
┃ design-capacity ┃ 76498.56 mWh ┃
┃ design-voltage ┃ 13.281 mWh ┃
┃ last-full-capacity ┃ 77534.478 mWh ┃
┃ state ┃ discharging ┃
┃ voltage ┃ 13.281 V ┃
┗━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━┛

It’s also available as JSON.

is known summary battery --json

{
 "state": "discharging",
 "battery-number": 1,
 "count": 1,
 "charge-rate": 0,
 "current-capacity": 76750.899,
 "current-charge": 99,
 "design-capacity": 76498.56,
 "design-voltage": 13.281,
 "last-full-capacity": 77534.478,
 "voltage": 13.281
}

"Lightning" by nathan_lounds is marked with Public Domain Mark 1.0 .

Read on website

Debounce All of the Things

Tue, 25 Feb 2025 00:00:00 +0000

"my pocket watch rules" by Cubosh is licensed under CC BY 2.0 .

The TL;DR
#

I created a tool to limit how often commands are run. It’s called debounce and I like it a lot. You can skip right to the repository to start debouncing, but today, I really want to tell a story.

The Caveat
#

Before I lay my soul bare, let me address in advance the kind of comment I anticipate receiving:

You can already do some or all of this with [some other tool]

I did this for the same reason I might solve a crossword puzzle. We don’t collectively give up on the puzzle because someone else has already solved it. The joy is in discovering the solution. For me, it’s a nice diversion. Some days when work has been a real slog and I haven’t gotten a lot of wins, working on something simple like this gives me an easy win and I just feel better about my life. Maybe this is my therapy. Please don’t take my therapy away from me, even if it’s just re-inventing wheels.

The Setup
#

Back in 2023, I wrote about is, which is essentially an experiment in making it easier to write shell scripts for different environments. In the intervening months I’ve used it basically every day and I’m quite happy with it. Somewhere along the way, I thought I could use is to prevent me from doing things like installing a nightly neovim build more than once per day.

The scenario is basically that in my dot-files I run installer scripts to take care of mundane tasks across the machines that I use. Whenever I want something new to happen across my environments I edit an installer script and run it to ensure that things work as expected. Often the first pass is broken in some way. I edit the script and run it again. I make it a point to do this in the script so that if I get distracted and move on to something else, my work is saved and I can commit it to my repo later. If I quickly whip something up on the command line, I often forget to add it to my dot-files.

The Problem
#

The problem arises when a task in an installer script takes too long. For instance, I may have a build step that installs the nightly neovim build. If the script fails after this point and requires multiple runs to fix, I have to wait for the nightly build install to happen over and over. That wastes time and network resources. I can do better.

Solution: Attempt the First
#

To address this, I added support for is cli age, which allows me to do something like:

is cli age nvim gt 1 day && ./installer/nvim.sh

is cli age will search my $PATH for an exact match on the provided name and then check its age. This is great, because I now have some granularity around when neovim might be installed. I can express it in days, minutes, or even seconds.

is cli age [filename] [gt|lt] [integer] [hours|minutes|seconds]

That’s it. If you prefer a shorthand, the following aliases are available:

hours | hour | h
minutes | minute | m
seconds | second | s

This allows us to express the same intent with fewer characters.

As an overall solution this is nice, but it breaks down really quickly for some other cases. Imagine I want to check for updates to other software which doesn’t have a nightly build. This particular example runs ubi to take care of installing/upgrading typos.

is cli age typos gt 1 day && ubi --project crate-ci/typos --in ~/local/bin

Here I’m not installing a nightly build, but rather a regular release. So if I run my installer script 10 times and there hasn’t been a new release in the last day or so, it will try to upgrade the binary 10 times. Sub-optimal.

Taking a Detour with Find
#

If you’re thinking “you can already do this with find”, you’re not wrong. Let’s look at this option.

find $(which nvim) -mtime +1 -exec ./installer/nvim.sh \;

It’s helpful to know that -mtime +1 means the file needs to be more than 1 day old. If you want it to be younger than 1 day, you would use -mtime -1. If we wanted to limit to 10 minutes, rather than a day:

find $(which nvim) -mmin +10 -exec ./installer/nvim.sh \;

So, to recap, -mtime is modification days and -mmin is modification minutes. If we wanted to limit to 30 seconds, then I don’t believe find has a convenient way to do this. It’s not terrible, but I just don’t love it. Also, don’t forget to add the \; at the end of the line, or this just doesn’t work.

To me using find is just not intuitive. I want a syntax that

feels natural
reads like English
I don’t constantly have to look up
works exactly the way I want it to

Solution: Attempt the Second
#

As established above, knowing the age of an installed binary is helpful when it comes to a nightly build, but when it comes to binaries which are released less regularly, it’s not great. I figured I could cobble something really primitive together, where I would touch a file at a known location after a successful installation attempt and skip subsequent installation attempts if a file exists at the known location and is younger than a specified time.

is cli age is meant to be used for things that exist in your $PATH, so I added an is fso age subcommand, where fso stands for “filesystem object” (a link, a directory, a file, etc). This means we can now do something like:

is fso age ~/.bash_profile gt 24 hours && echo "this file is not new"

This gives us an easy way to ensure that the last modified time of a file is younger or older than a certain age. We will leverage this below, in order to create a simple Bash debouncer.

Creating a debounce Function in Bash
#

What does debouncing mean? ChatGPT explains it as:

Think of debouncing like pressing a button that triggers an action. If you press the button multiple times in quick succession, it might cause the action to be triggered repeatedly—sometimes unnecessarily. But, if the button is debounced, it only triggers the action once, no matter how many times you press it, as long as it’s within a set time window.

For our purposes, we can think of debouncing as a way of telling the Operating System to:

run this command, but only if it hasn’t successfully been run within the last X seconds/hours/days".

Consider the function below:

db() {
 if [ $# -lt 3 ]; then
 echo "🤬 Not enough arguments provided. Usage: debounce 6 h something"
 return
 fi

 # exit as early as possible if we can't create the cache dir
 # test -d appears to be slightly faster (3ms?) than mkdir -p
 cache_dir=~/.cache/debounce
 test -d $cache_dir || mkdir -p $cache_dir

 number=$1
 units=$2
 shift 2

 # everything remaining is runnable
 target="$*"

 # file is $target with slashes converted to dashes
 file=$(echo "$target" | tr / -)

 debounce="$cache_dir/$file"

 if [ -f "$debounce" ] && is fso age "$debounce" lt "$number" "$units"; then
 echo "🚥 will not run $target more than once every $number $units"
 return
 fi

 "$@" && touch "$debounce"
}

We can now run our function like db 12 hours npm install.

To break it down, db does the following things:

requires 3 (or more) arguments, in the form of db 12 hours npm install
creates a cache directory, if none exists
transforms the given command (in this case “npm install”) into a cache file name
checks if the cache file exists and it’s younger than the provided age check (12 hours here), if this is true it
- prints a message to assure the user that no code will be run
- returns
runs the command in all other cases
if the command succeeds (exit code 0), it will touch the cache file, so that we have a timestamp which subsequent db runs can use as a reference time

This is simple and it works. It doesn’t require much, other than having is available to do the file age comparison. For simple commands it is quite straightforward. You can even look at the cache directory to see the names of commands which have already been run, which means that a simplels will tell you when they were last successfully run to completion. It’s not bad.

However, this breaks down once you get longer and/or more complex commands.

Do I need to start worrying if the length of the generated file names will exceed OS limits?
What about && and || and other special shell characters?
- How will I encode them in the file name?
- Will it still be readable? Is there some kind of security risk to this approach?
What if I want to run the same command in different directories, but each needs their own cache file?

Solution: Attempt the Third
#

I could work around the limitations of the previous function, but it would require writing more Bash code. I don’t mind a bit of Bash to get me where I need to be, but at some point I’m more comfortable doing this in a different language. I chose to re-implement this in Go. I could have done this in a number of other languages, but I chose Go because goreleaser makes it easy for me to distribute a binary that I can install via ubi. My other solutions already depended on is, so there was always going to be some kind of dependency.

The new binary is called debounce. Let’s try it out:

$ debounce 1 day installer/nvim.sh
# installer runs...

$ debounce 1 day installer/nvim.sh
🚥 will not run "installer/nvim.sh" more than once every 1 d

How much delay does debounce introduce? On an M3 MacBook Air we get:

$ time debounce 1 day installer/nvim.sh
🚥 will not run "installer/nvim.sh" more than once every 1 d

real 0m0.005s
user 0m0.002s
sys 0m0.002s

🚀 Not much delay at all. What if I want to check when the next run is scheduled, without executing the command?

debounce --status 1 day installer/nvim.sh
📁 cache location: /Users/olaf/.cache/debounce/bdb61146922d63f599045bde35c65d0606e002f88bc3099554c644ff153e11df
🚧 cache last modified: Mon, 24 Feb 2025 21:37:13 EST
⏲️ debounce interval: 24:00:00
🕰️ cache age: 00:02:56
⏳ time remaining: 23:57:03

That’s the available debounce metadata. We can always wipe out the cache file to start fresh.

$ rm /Users/olaf/.cache/debounce/bdb61146922d63f599045bde35c65d0606e002f88bc3099554c644ff153e11df

$ debounce --status 1 day installer/nvim.sh
Cache file does not exist. "installer/nvim.sh" will run on next debounce

The Tips
#

Running Multi-Step Commands
#

Use bash -c if your debounce command is really a series of chained commands.

debounce 2 s bash -c 'sleep 2 && date'

Careful with Your Quotes
#

If you need your variables to expand only at the time when your command is running, use single quotes.

debounce 10 s zsh -c 'foo=$(date) && echo $foo'

The debounce in Your CI/CD Pipeline
#

If you’re using debounce in CI/CD, you’ll want to ensure that your cache directories are preserved between runs. You may find the --cache-dir flag helpful here.

The debounce in Your Ansible
#

Maybe you want to run database backups, but no more than once per day.

- name: Perform debounced database backup
 command: debounce 1 day ./back-up-database.sh

I can think of other use cases, like making sure you’re not pushing to (or pulling from) Docker hub too often. How about using a cron to retry a query against a flaky web service?

*/5 * * * * /path/to/debounce 30 m /path/to/fetch-exchange-rates.pl

Under this scenario, fetch-exchange-rates.pl will be run every 5 minutes until it successfully fetches the latest exchange rates. Then it won’t try again for another 30 minutes. At that point it will continue to run every 5 minutes until it once again achieves success. And so on.

The Conclusion
#

There are lots of possibilities here. Think about where you re-run logic unnecessarily. Maybe debounce could help?

For any more questions, I refer you the debounce repository. There is no way to comment on this blog, so you’ll have to go to GitHub to tell me how much you hate this idea. 😅

Until next time!

is: an inspector for your environment

Read on website

How I Spent My First London Perl Workshop

Fri, 08 Nov 2024 00:00:00 -0500

Look Who’s Back
#

Earlier this year I was excited (one might even say well chuffed) when I heard that the London Perl Workshop was coming back after a hiatus of several years. I knew that in all likelihood I would not be able to attend, but it has been a bucket list item of mine for quite some time. You may be thinking to yourself that I have a weird bucket list. You’re not wrong.

I made no plans to attend, since I would be using my professional development days to attend The Perl Toolchain Summit. I thought I might make a short trip with my remaining budget to a conference in NYC or Chicago, since those destinations are easy to get to from Toronto.

Fast forward to October. The US conferences which had I found were fairly expensive. I wouldn’t be able to fit a conference pass, airfare and hotel with my remaining (or even entire) budget. I optimistically crunched some numbers around attending the London Perl Workshop.

To my surprise, I could make the travel and hotel costs work within my budget as long as I didn’t stay any longer than from Friday to Monday. Since the workshop is free, I didn’t have to worry about splashing out USD 600 for a day at a conference. I casually floated to the MetaCPAN crowd that I was thinking of a long weekend in London. Leo decided to come down as well so that we could hack on MetaCPAN in the time around the workshop. Mickey had already planned to come. Mohawk, who hangs around in our IRC channel, would be there as well. So I already knew I’d be in good company.

My manager signed off on the trip and my family decided I wasn’t so important that they couldn’t do without me for a few days. I was off to London. I would not be missed.

Wheels Down London
#

Small Square Cafe

I flew out late on Thursday night, arriving early Friday morning. I dropped my bags at the hotel, planning to check in after lunch. I found a really nice little coffee shop and then walked over to Denmark Street. That took about an hour. Mickey had said there were some cool guitar shops there. I wasn’t too excited about looking at gear I couldn’t afford, but it did sound interesting. It’s a very short street and I saw Mickey and Sawyer on the sidewalk within a few minutes of arriving there.

No.Tom Guitars

Mickey took me into a couple of guitar shops. In the first shop that we visited Richard Ayoade popped in to look at a guitar. We all played it cool and didn’t bother him, but bumping into someone from The IT Crowd so shortly after my arrival did bode well. Actually, based on the length of my trip, Travel Man was also a good fit.

1931 National Style 4 Guitar: 12,000 quid

1914 Gibson Harp Guitar: also 12,000 quid

Next we ran into Leo on the street and we collectively decided to head for lunch. The result was most excellent. At this point I was well gruntled as the locals may or probably may not say.

We did a bit of walking and then stopped for cake and coffee. Then we did a little more walking and some shoppinng. Eventually we headed down to the pre-workshop social. We immediately saw some familiar faces. It was great to reconnect with people.

Honey Cake

The Pre-Workshop Social
#

I had been feeling somewhat proud of myself for flying in to London just for the weekend – and all the way from Canada. Surely that was impressive or something? All of that became largely moot when Kenichi Ishigaki walked into the venue, having arrived from Japan this same day. I hung my head in shame, knowing I had been bested. He also was returning home on Monday like I was. Very impressive stuff on his part. My trip was mere child’s play in comparison.

At some point the venue got incredibly loud. I felt like I was losing my voice. Leo, Sawyer, Mickey and I set out to find some dinner. That was also more than sufficient. Eventually we got back to the hotel. It was maybe 11 pm. In all of the excitement I didn’t get a chance to take a nap or even change out of my overnight airplane clothes. I was ready for a solid night of sleep.

The Workshop
#

On Saturday morning, Leo and I headed down to the conference on foot, since our hotel was quite close to the venu. We grabbed a coffee on the way and then did the registration, which consisted of putting your name on a name tag and getting your conference scarf. Providing a scarf as swag means the organizers don’t have to take sizes or different styles into account. Very smart.

Here I had the chance to (re)connect with even more people, since just a small fraction of the attendees had been at the Friday evening social. The event was incredibly well attended. The vibe was positive, with lots of laughs and lots of interesting talks.

I attended Dave Cross’ talk first and we got to have a quick chat. I had missed connecting with him in Toronto in 2023, so this was the first time we had met in person. I have been pestering him online for a while now, so it was nice to meet face to face. I also made it a point to reserve Mohammad for lunch before he got scooped up by someone else, since I really didn’t have a good chance to speak with him in Toronto either. That turned out to be a good plan, as he was unable to attend the evening social. He also gave me a lovely gift to welcome me to London. What an incredibly kind person. I should be giving him gifts to thank him for all he has done to amplify my blog posts in the Perl Weekly.

Lunch was Mohammad, Paul Cochrane, Mickey, Sawyer and I. Sawyer gave a technical presentation on my laptop as we waited for the food to arrive. I learned a bunch. It was nice to have Paul along since I have also been pestering him online for a while. He doesn’t seem to mind. 🤞

I had a chance to meet Stuart MacIntosh (president of The Perl and Raku Foundation) in person. I have been working with Stuart and TPRF on sponsorship and fundraising for the last 6 months. After many video calls we could finally chat in person. I also was able to corner Mark Fowler, who worked on a team with me for many years but sadly now works at CircleCI. That’s sad for me (not for him or CircleCI). Mark is the creator of The Perl Advent Calendar. This is the 25th year of the calendar. I doubt he had that kind of longevity in mind when he was inspired over drinks to get this project out to the world.

The afternoon talks were also interesting. I won’t go through an inventory. Likewise, I won’t name every single person I met – but I probably could.

I should add that I found Theo’s lightning talk tribute to Abe, whom we lost just a short while ago, to be quite moving.

After the event many of us went out for social drinks, which was nice. Julien Fiegehenn sat with us at the pub. I guess I am still name dropping. 🤔

Leo, Mickey, Sawyer and I went out to find some dinner. As we were about to order our food, it became clear to me that I was starting to reach my limits, so I left them to order their curries without me and headed back to the hotel to sleep. I was trying to be thoughtful by leaving before food was ordered, lest something go to waste. Apparently in my absence the 3 of them ate a meal meant for at least 4 people. Kudos to them and their hardy (hearty?) appetites.

Thoughts on the Conference
#

Before I get into stories about hacking, I’d like to share some thoughts on the conference itself.

It was really well organized. Thanks to Lee and Julien and everyone who helped organize and volunteer on the day.

There was a great mix of people. There were:

Older people
Younger people
Working people
Retired people
A large number of attendees who had never been to this workshop before
A number of attendees who had never been to a Perl workshop before

As I looked around the room, I saw people who were there to reconnect with old friends, people who were looking to make new friends and a collective of quirky, off-beat, nice people who came together out of a shared enthusiasm for arcane knowledge and niche programming languages. It’s a place where everyone can feel welcome and where you can give a talk about scratching some weird itch while your peers listen silently to your every word.

I hope this conference happens again soon. It was a real pleasure to attend.

A Miniature meta::hack
#

Sunday morning began with finding coffee and then hacking in the hotel lobby with Leo, Mickey and Sawyer. Before I headed to London, Julien had asked me if I had a location for hacking. I said “maybe in one of our rooms?” He reminded me that this is London and I was just a naive child. He was right, of course. I could barely walk around my bed. If I flipped down my tiny table, I couldn’t even do that. Luckily the lobby cleared out after breakfast. After that we had access to long tables, lots of electrical sockets, water, coffee and snacks.

I began the day by working on our AWS-hosted Elasticsearch instance. Elastic kindly sponsored us with a cloud instance earlier this year when I reached out to them, but we hadn’t been able to fully take advantage of it. It set out to work on getting the cloud instance basically up to date with production data and working with Mickey on his Docker setup, which has been affected by a kind of “move fast and break things” by people who are not named Mickey. That all worked out well.

Later in the morning, Julien stopped in to hack with us. We all stepped out for lunch and then Mickey and Sawyer headed off to the airport. Julien took me and Leo on a sightseeing tour and then we headed back to the hotel for more hacking. After lots of screen time, we found a really nice Chinese restaurant. After eating, Julien headed home and Leo and I got back to hacking. I probably could have gone to bed, but I had left something in a broken state and it was going to eat away at me if I didn’t deal with it before bedtime. That worked out well and I was able to sleep like a baby.

Gherkin Building

Olaf at Bridge

Hack Day, The Last
#

I got up at 6 AM on Monday to go for a run. I started off moving towards the external setting for “Slough House” as it appears in my beloved Slow Horses. I then looked for more interesting places to explore. I love seeing a city on foot this way. I can cover a lot of ground and I’m also getting my workout. An added bonus is that I have a Strava map of the run as a kind of souvenir after the trip. I have fond memories of running in Oslo, Paris and Lyon at the various Toolchain Summits. If I’m going to be doing that much sitting, I owe it to myself to spend some time where I am definitely not sitting.

Slough House

Arch

Narrow Building

Wall Garden

Phone Booth Library

Upon my return, Leo treated me to a bacon and egg sandwich with ketchup. I’m not going to lie – it was delicious. As we ate in this tiny shop we were able to watch the regulars come by and order “the usual”. I wish I had a place like this close to me. My lack of a cozy sandwich shop near my own home is likely better for my cholesterol, but YOLO.

A delicious bacon and egg sandwich

After breakfast we did some more, you guessed it, hacking. Over sandwiches Leo got me to realize that my plan to test a staging environment with the cloud Elasticsearch was fine, but what was I hoping to learn? I explained to him exactly what I was hoping to learn and it’s fair to say, I was not going to learn much. So, I deployed the cloud Elasticsearch to the production. We could toggle back to the bare metal Elasticsearch if this turned out to be a mistake.

To my surprise, the cutover was so painless that I’m not sure anyone noticed. The hosted Elasticsearch had data that was at least a day behind production. I re-ran the indexer on all releases in the previous 48 hours. Now we were basically caught up. (There did turn out to be an issue with a couple of indices which are not related to search – Graham sorted these out on the following day).

I don’t have any benchmarks to prove it, but the site now feels faster to me. I had been worried about the lag between the data centres when going to a remote Elasticsearch, but it’s quite possible that the powerful system running the new Elasticsearch is more than making up for any increased latency. For the time being we have front end containers running in Frankfurt. They talk to back end bare metal servers in the UK. The bare metal back ends speak to the hosted Elasticsearch in Frankfurt. Eventually everything should reside in Frankfurt, but that’s a conversation for another day.

Aside from no longer needing to worry about keeping 3 Elasticsearch nodes up and running on bare metal, we are now in a position to upgrade from Elasticsearch 2.4 to 5. Then we’ll move to 6 and so on. Being able to migrate from one cloud instance to another will be far easier than trying to allocate enough hardware to run two concurrent versions of Elasticsearch during an upgrade. I would never point to the cloud as a solution for everything, but in this case the benefits have become very clear to me. I would like to thank Elastic for their commitment to The Perl Community. They have been incredibly helpful.

This Elasticsearch cutover was the conclusion of work which began 6 months ago at the Perl Toolchain Summit in Lisbon. Emotionally it feels really good. The bulk of the work happened in bursts, generally when some of us were in the same room or just around the time. I think remote work is amazing and I would strongly advocate for 100% remote work, but there is still real value in face to face meetings. I’m glad we were able to make this happen.

After going live to production and not seeing anything go up (down?) in flames, Leo and I headed to Paddington Station. He took his train home and I filled any remaining gaps in my luggage with junk food for the kids. I’m not sure if that makes me a good or a terrible Dad, but a precedent has been set by past trips and at this point I’m not sure I’m in a position to break with it.

As I sit in my Air Canada flight, somewhere over Newfoundland, I now look forward to seeing some smiling faces at home and hopefully being attacked by a completely out-of-her-mind 75 pound dog. And I’m already thinking about how I can once again make it across the Atlantic to get some work done.

Read on website

I'm Still Lazy

Wed, 28 Aug 2024 00:00:00 +0000

This toy was somewhat broken
#

About six years ago, I wrote about lazy, which is a tool that will auto-install Perl dependencies for you as they are required. It’s not unique – it has been done before. But this implementation uses a different installer (cpm) and it also allows you to pass in some flags directly to the installer. I think it’s fun, but it had some problems and it didn’t always work the way I wanted it to. I should have fixed it sooner, but I’m lazy.

Today I wanted to use it and I was so annoyed that I decided to have another look at it. But, it was after my work day and I was feeling lazy. So I asked GitHub Copilot to fix the biggest bug for me. It was deep recursion. Surprisingly, Copilot immediately grasped and fixed the issue. (At least it seems that way to me). Once that was done I took a closer look and decided to fix some design decisions that were making the internals overly complicated. I did that on my own. Then I added some GitHub Actions to give me a little more confidence in my changes and soon it was ready to ship.

Now it’s a better toy
#

As of right now version 1.000000 of lazy is now available for you to download. You can check it out on MetaCPAN.

Have some fun with it
#

At the command line
#

# Auto-install missing modules globally
perl -Mlazy foo.pl

# Auto-install missing modules into ./local
perl -Mlazy='-Llocal' foo.pl

# Auto-install missing modules into ./some-other-dir
perl -Mlazy='-Lsome-other-dir' foo.pl

In your code
#

# Auto-install missing modules globally
use lazy;

# Auto-install missing modules into ./local
use local::lib;
use lazy qw( -L local );

# Auto-install missing modules into ./some-other-dir
use local::lib qw( some-other-dir );
use lazy qw( -L some-other-dir );

# Auto-install missing modules into ./some-other-dir and pass
# more options to App::cpm
use local::lib qw( some-other-dir );
use lazy qw( -L some-other-dir --man-pages --verbose --no-color );

In a one-liner?
#

Install App::perlimports via a one-liner, but why would you want to?

$ perl -Mlazy -MApp::perlimports -E 'say "🧅"'
🌍 global install if required
DONE install Net-SSLeay-1.94
DONE install IO-Socket-SSL-2.088
DONE install LWP-Protocol-https-6.14
3 distributions installed.
skipping autoloader file auto::Net::SSLeay::DTLS1_VERSION.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
skipping autoloader file auto::Net::SSLeay::DTLS1_VERSI.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
skipping autoloader file auto::Net::SSLeay::DTLS1_2_VERSION.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
skipping autoloader file auto::Net::SSLeay::DTLS1_2_VER.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
skipping autoloader file auto::Net::SSLeay::DTLS1_BAD_VER.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
skipping autoloader file auto::Net::SSLeay::DTLS1_BAD_V.al at /Users/olaf/.plenv/versions/5.40.0/lib/perl5/site_perl/5.40.0/lazy.pm line 90.
DONE install Mozilla-CA-20240730
1 distribution installed.
DONE install Regexp-IPv6-0.03
1 distribution installed.
DONE install Net::SSLeay is up to date. (1.94)
0 distribution installed.
DONE install IO::Socket::SSL is up to date. (2.088)
0 distribution installed.
DONE install App-perlimports-0.000055
1 distribution installed.
🧅

And that’s really it. I hope you have fun using it. I hope it makes you more productive. But, most importantly, I hope it leaves you more time in the day to goof off and, you know, just be lazy.

Read on website

How I Spent My Perl Toolchain Summit v2024 (Lisbon)

Fri, 21 Jun 2024 00:00:00 +0000

PTS 2024 in Lisbon
#

The Perl Toolchain Summit (PTS) is an annual event, held in Europe, where work on improving the Perl toolchain takes place. I was fortunate to be able to attend PTS once again this year. This year we gathered in Lisbon, Portugal from Thursday, April 25 to Sunday, April 28. This was my 1st trip to Lisbon and my 9th PTS in total.

Getting There
#

Last year, I took my little travel companion along for the ride. That didn’t work out for us this year, so I flew solo, but I missed the company.

On the Monday evening I flew out from YYZ. Early Tuesday morning I had breakfast in Paris at CDG and then continued on to Lisbon.

[Canelé in Paris. The stop at CDG was worth it]

Getting Settled
#

[On the descent into Lisbon, the view of the sandy beaches was incredible.]

My initial plan had been to spend Monday or Tuesday at the beach at Cascais, since I had never swum in the ocean before, but INGY had thrown out the idea of renting some road bikes in Lisbon and doing some cycling. The choices were a 40km route with some tough climbs and an 80 km route with less climbing. I had never gone on a ride of more than 65 km, but after some discussion we decided on the 80 km route as that seemed like the easier option.

After checking in at the hotel, Ingy and I picked up our rental bikes and rode them back to the hotel. It was my first time on cobblestones with a road bike and I experienced almost immediately how much fun that is. After I picked myself up off the ground I was decidedly less enthusiastic about riding, but the rest of the way back to the hotel was not so eventful.

Fado
#

In the evening, Ingy and Tina and I went out to dinner with some local friends of Ingy who had kindly booked us all a table at a local restaurant which serves wonderful food with performances of Fado in between. The musicians were extremely skilled and the audience was very appreciative. This was complemented by the quality of the food and wine. It really was a night to remember. The only thing we didn’t remember was to get to bed early. I got back to my room at 1:30 AM and I needed to be on my bike 6 hours later. I hadn’t taken a proper nap or thought too much about jetlag as there hadn’t really been time.

To Ride or not to Ride
#

After getting back late, I decided I probably shouldn’t ride the next day. My leg was still a bit sore from my fall, I had a headache from riding on the cobblestones and (I’m not going to lie) I had had a fair amount to drink. I debated how I should cancel on Ingy. Should I send him a text now and let him know that I had made the safe, responsible, adult choice or should I casually mention at 7:00 AM breakfast that I wasn’t feeling up to it? I decided to let him know at breakfast.

By the time I was having my 7:00 AM breakfast, my headache was gone, my leg was healing nicely and I wasn’t so tired. Also, given how much I enjoyed the ride from the bike shop to the hotel, I wasn’t looking forward to returning the bike to the shop by myself. I figured I’d ride along and see how it all played out. How bad could it be? If at any point I wanted to bail on the ride, I could find a train and head back, so I headed out with a contingency plan.

After maybe one minute of riding it became obvious to me that I didn’t have the speed or the bike handling skills to keep up with Ingy and his local friend (who had taken us out for dinner just a few hours ago and was now very kindly taking us on one of his local routes). There was no way I was riding between two rows of stopped cars on the cobblestones, even with 30 mm tires. However, it was a “no drop” ride and they kindly waited for me at points along the way to ensure we stayed together. We had a really nice ride along the coast. The temperature was around 17 C and there was barely any wind. It really was optimal as far as conditions went. I didn’t even get a sunburn. Luckily we did make a stop for a delicious espresso and custard tart. I had lacked the foresight to bring any kind of food with me, so that made a real difference.

[Espresso and a tart for everyone]

We rode for a long time. Like a really long time. There were long twisty climbs, long twisty descents and the occasional flat sections. No parts of my body let me down and I finished without picking up any new injuries (except for the limp which I sported for the next two days). The 80 km ride ended up being a 110 km ride, clocking in at 4 hours and 43 minutes.

After the longest bike ride of my life I was not really in the condition to go for a swim at the beach. Ingy and I headed out to the older part of town to get some Ginjinha.

I then struck out on my own in the older part of town, got myself some custard tarts and made it back in time to get to the arrival dinner as food was being ordered. It was nice to see old friends after a one year break and to meet some new faces as well. On the way home we stopped for ice cream at a shopping mall. I couldn’t wrap my head around the fact that the mall is open until midnight every night. I’m lucky when my local malls are open until 9. Some evenings they close at 6. The Portuguese way is better.

[A Portuguese style burger from an Irish style pub]

Day 0
#

On Thursday morning, we started with a short standup meeting and then people split into groups of one or more to make plans and get hacking.

Our plan was two-fold:

Begin moving more of our infrastructure into the cloud, via Kubernetes
Begin moving our Elasticsearch data from bare metal to the Elasticsearch hosted offering.

The reason we are able to move our data to a hosted offering by Elasticsearch is because Elastic is our newest sponsor. I had reached out to Elastic shortly before PTS to ask if they could help us out. They quickly responded by saying that they would like to support the Perl community. In the next day or so I had a meeting with their developer relations contact and we got immediate access to all of the resources which we required. This is a huge helping hand for us in keeping the project moving forward. It will allow us to have better uptime and also will give us better tools for migrating from our very old v2.4 Elasticsearch to a more modern v8 version. My personal thanks to Elastic for making this happen!

As Leo and Joel got to work on the kubernetes end of things, Graham made various code improvements around the indexing of Perl itself, which requires some special casing. Mickey began reworking the indexer code in order to make a future Elasticsearch upgrade easier.

I mostly got down to administrative things.

I had to submit a bunch of receipts to Open Collective so that they don’t suspend our virtual credit card.
I purged some very old data from our S3 buckets so that we’re no longer being billed for hosting it.
On this day we also became aware that the disk on our primary hosting machine was in read-only mode. Leo switched the cron jobs to another machine, but our Minion queue was not running. I spent much of the afternoon debugging this issue. I was successful and we shut down the old machine. Our 3 machine cluster at Bytemark was now reduced to 2, but we still had enough redundancy to get by.

After this I began looking at the Elasticsearch snapshot restore process, but I just couldn’t get it to work on my first attempts.

Day 1
#

We started with standup once again and then got to our various tasks. I began again with trying to restore an existing Elasticsearch snapshot from our production machine into the Elasticsearch cloud. I was aware that this could be tricky, since 2.4 is no longer a supported version of Elasticsearch. We were able to get a 2.4 Elasticsearch in the cloud provided to us, but the caveat was that it might be tricky to set up, given the amount of intervening years since it was released. That was entirely fair. I spent some time trying to find the correct incantation for registering our s3 bucket with Elasticsearch and I was coming up against slightly cryptic errors which were being proxied back from an AWS Java library. Leo also sat down with me to try to make some progress. Eventually we had to admit defeat on that for the day and move on to something else.

Unrelated to MetaCPAN, I merged a PR for p5-www-youtube-download. That library hasn’t worked in a while, but apparently it’s now less broken. However, since some of the tests are still broken, someone may need to look into that before I can release. I don’t use this software at all. I’m happy to merge and release but I don’t feel like it’s a good use of my time to be spending a lot of effort on it.

I sat down and spent some time with ABELTJE, who is moving test-smoke.org into the MetaCPAN infrastructure so that he is no longer solely responsible for maintaining the site. He was in the process of Dockerizing the site and was 95% of the way there. Together we ironed out the final bit and got his Docker containers running locally.

There was also a discussion about settling the Perl logo question, which NEILB participated in via Zoom. I think we made some good headway. We had a number of stakeholders in the room and after some hearty debate, I’m hopeful we can move ahead with this in the near future. Watch this space.

I also did a fair bit of code review as Graham works at a furious pace and I didn’t want to slow him down.

Day 2
#

I believe this day may not have begun with standup. As is tradition, standup usually gets stood up somewhere along the way as jetlag and late nights catch up with attendees and they trickle in later and later on subsequent days.

Since we are looking at a fair amount of future code churn in the metacpan-api repository, I thought it would be helpful to get code coverage metrics going on it and metacpan-web. metacpan-web was fairly easy to set up as it runs in GitHub Actions. It has multiple builds, two of which do not use Docker. metacpan-api, on the other hand, was a different case. It only runs tests via docker compose and that all happens on CircleCI. We do this because CircleCI allows us to select a machine size (we want as large as possible) and it allows us to re-run failed builds with an open SSH connection to the container. To be honest, the SSH thing is a game changer. I absolutely love it and I’m not just saying that because CircleCI mailed me a shirt and socks recently. 👕 🧦 😀

I did not finish this project, but it was a good start.

On this day ABELTJE sat with us and I worked with him on automating the build of his Docker images via GitHub Actions. The actions now push images to the MetaCPAN Docker Hub account, which is a vital step in deploying test-smoke.org on his behalf.

Perhaps the most exciting news is that I finally got the Elasticsearch snapshot restore working. I had gotten some help via email from the Developer Relations person at Elastic and this set me on the right path. Basically I needed to provide an extra key in the JSON I was sending to register the bucket. I don’t think this key was specifically mentioned in the docs, but I stumbled over something that gave me the idea to try. I’m happy to say that we now have a very large amount of data in the Elastic cloud, which will make it much easier for us to move ahead with future upgrades.

My abject failure to meet the moment when it came to writing a few curl commands had left me wondering if I had any purpose at all being in the same room with people who are smart enough that they surely would never find themselves stymied by such a banal task. I try not to let my professional life define my self worth, but this one had been messing with my mind. However, now buoyed by my victory over AWS, Java and a possible gap in documentation, I was once more fighting fit. I was, indeed, The King of the World.

Soon it was time to celebrate with food. I like to make it a point to try local cuisine and, on this evening, a group of us headed out to for a traditional Portuguese dinner. Joel found us a venue using Google Maps, assuring us with great confidence that he was quite skilled in this regard. He did, in fact, lead us to a very nice restaurant. As we were seated it became clear that the restaurant was Spanish. As we pondered our options for paella, Joel helpfully pointed out that Spain was at least geographically quite close.

Day 3
#

On this day I began by revisiting the test coverage work. We could have moved on without it, but to be honest, it was really bugging me that I couldn’t figure it out. It took some messing around to get this to work. It’s essentially installing Devel::Cover inside a Docker container and then running the tests via docker compose. Once that is done we install Devel::Cover and some libraries required by Codecov outside of Docker. We then generate and upload the report from outside of the container. It’s easier to upload reports from outside of the container, because there we have all of the CircleCI environment variables which are required at upload time.

That’s all working nicely now and I’m quite happy with it. I’m also a little surprised at some of the code coverage gaps we have. 😅 Kudos to PJCJ for continuing to make this one of the most helpful Perl modules ever.

A side effect of this work is that I was able to spend some time looking at the CircleCI docs, comparing their current open source offering with our current usage. I realized that we could bump our VM size from medium to large. This decreases the build time by about 30%, reducing the build from ~20 minutes to ~14 minutes. There may be some more speed gains to be had, but this was a great improvement to start with.

I also spent a bit of time on administrative work, reaching out to TPRF to secure email hosting for smoke-test.org, as we don’t want to email in future when the domain name is transferred to TPRF. We had transferred the MetaCPAN domain name to TPRF a number of years ago in order to reduce the bus number on our project. I think that was a good approach.

I also began the work of configuring the API to talk to the new Elasticsearch in the cloud. Currently the API allows for the Elasticsearch connection to be set via:

a series of Apache-style config files which are merged via Config::ZOMG
a series of .pl files which are evaled and then merged into a HashRef
environment variables
some hardcoded defaults

That’s kind of fun. These things evolve organically over time and there are good reasons for all of them to exist, but that doesn’t make them easy to work with or necessarily easy to understand. I began tearing down a lot of this config and moving everything to the Apache-style configs which Catalyst is expecting. I don’t love this, but it’s better to have this logic in one place. I ended up with a giant “Work in Progress” commit which I pushed to GitHub. It breaks things and I haven’t figured all of it out yet. Over the next little while I’ll probably tease that apart into smaller chunks that can be committed as a series of pull requests. I wasn’t all that hopeful that a scorched earth approach would “just work”, but you never know. I’m generally encouraged by the progress of this work, though.

The Sponsors
#

This event wouldn’t take place without the financial backing of our wonderful sponsors. I’d like to thank the following donors for making this event a reality:

Booking.com, The Perl and Raku Foundation, Deriv, cPanel, Inc, Japan Perl Association, Perl-Services, Simplelists Ltd, Ctrl O Ltd, Findus Internet-OPAC, Harald Joerg, Steven Schubiger. In kind sponsors: Fastmail, Grant Street Group, Deft, Procura, Healex GmbH, SUSE, Zoopla.

The Attendees
#

As pictured below, this year we had Leo Lapworth, Graham Knop, Olaf Alders and Mickey Nasriachi in attendance to work on MetaCPAN. Not pictured is Joel Berger. He’s missing because this picture is from 2023. ¯\_(ツ)_/¯

We once again missed Shawn Sorichetti very much, as he was unable to attend.

Photo © Salve J. Nilsen, 2023, CC-BY-NC-4.0

Welcome to Our Newest Sponsor
#

As mentioned above, Elastic recently joined us as a sponsor. If your company would like to help us continue to make finding Perl modules enjoyable, please do have a look at our sponsorship opportunities and reach out to us at noc@metacpan.org with any questions.

Cascais
#

Around 5 PM on the Sunday evening I headed out to Cascais to go for a swim. I had seen the beach on our bike ride and I was excited to visit. The air and water temperature were 17 C. That’s still a bit chilly in the water, but sometimes that’s as good as it gets in Lake Ontario even on a summer day.

I hadn’t packed a wetsuit, but I managed around 35 minutes in the water before it became clear that it was time to get out. It was a great experience. I got to feel the salt water in my mouth and on my skin, in addition to taking in some lovely scenery from the water. I was a bit numb when I got out, but eventually the feeling completely returned to my feet. It only required about an hour of waiting, followed by a hot bath.

Heading Home
#

On Monday morning Leo and I headed across the street to buy a lot of custard tarts to take home. I should note that I ate custard tarts most days that I was there. I ate more than one per day. I even ate them fresh from the shop, when the pastry was particularly flaky and the custard had not yet fully set. It was a special kind of delicious and far better than the tarts I’ve been getting at home. I also learned that you can take them up to the next level by sprinkling a little bit of cinnamon on top. That’s possibly one of the most important things I learned on this trip.

Leo, ABELTJE, LEONT and I headed to the airport around 10 AM. I then got on a plane to CDG in Paris where I spent 3 hours eating pastries, chocolate mousse and browsing. After that it was on to YYZ, arriving around 9 PM and heading back to my normal routine, which included insisting that my kids eat custard tarts before going to bed.

Looking back on the week, I realized that I never had time to deal with (or even acknowledge) jetlag after arrival, because all of the days were filled with activities. On the return trip I started work the next morning and just got back to life as usual. For whatever reason it just worked out. I had one 45 minute nap, face down on my office floor, but other than that no issues. I have no idea why.

That’s a Wrap
#

I want to thank Breno, Philippe, Laurent and Neil, for all of their work in organising this event. It was incredibly well organized. Portugal had not been on my short list of places to visit, but I’m so glad that I was able to make this trip. It was well worth it.

Aside from having had a most excellent time, I’m mentally in a much better place than before I attended. I wasn’t in a bad place before, but I’m enjoying my work more right now and I’m enjoying chipping away at MetaCPAN. Collectively, we’ve maintained some momentum since PTS has ended and we’re continuing to get work done. It’s one of those side effects of conferences like these. Hopefully you get good work done at the conference, but sometimes the work leading up to and following on from the meetup can be just as important.

Read on website

One Line Fuzzy Find for Git Worktree

Fri, 14 Jun 2024 00:00:00 +0000

"Magnifying Glass" by Birmingham Conservation Trust is licensed under CC BY 2.0 .

The Backstory
#

I’ve written on fuzzy matching with fzf before. I’ve covered adding tab completion to an existing command, using fzf to get a file preview windows and combining tab completion and preview windows to improve an existing command.

Those are helpful things to do and I use them all the time, but today I’d like to cover a much simpler use case – a one-liner to allow you to use fuzzy matching to navigate git worktrees. If you’d like to read up on why you may want to use worktrees in git, I’ve covered that in 4 Strategies for Context Switching in Git.

Just Show Me the Command
#

You’ve heard enough from me by this point. Let’s try the command below. If you’re playing along at home, you’ll need to be inside a git repository.

Note: if you’re in a repository where you have not explicitly created a worktree, you’ll only get one result in the list, since git repositories by default exist in a worktree.

cd "$(git worktree list | fzf | awk '{print $1}')"

If you have more than one worktree in your repository, you should see something like this:

 /Users/olaf/.worktree/Perl-Advent/oalders/santa-picks-nits c312df9 [oalders/santa-picks-nits]
 /Users/olaf/.worktree/Perl-Advent/oalders/perlimports a8884db [oalders/perlimports]
>> /Users/olaf/Documents/github/perladvent/Perl-Advent 2a3d745 [oalders/new-index.html]
 3/3 (0) ───────────────────────────────────────────────────────────────────────────────────────────────────
>

Once you begin typing, the matching begins:

 /Users/olaf/.worktree/Perl-Advent/oalders/perlimports a8884db [oalders/perlimports]
 /Users/olaf/Documents/github/perladvent/Perl-Advent 2a3d745 [oalders/new-index.html]
>> /Users/olaf/.worktree/Perl-Advent/oalders/santa-picks-nits c312df9 [oalders/santa-picks-nits]
 3/3 (0) ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
> nit

At this point a return will cd you to the worktree of your choice, or you can opt out via ctrl-c.

Let it Live in a Function
#

To make this easier to use, you can store it in a function:

cd_worktree() {
 cd "$(git worktree list | fzf | awk '{print $1}')"
}

If this is in your .bashrc or some other place that gets sourced by your environment, you can have access to this selector via the function name directly at the command line:

$ cd_worktree

Or Put it in a Script
#

This works too:

#!/bin/bash

set -eu -o pipefail

cd "$(git worktree list | fzf | awk '{print $1}')"

How About an alias?
#

You might find a way to mash this into an alias, but I should point out the following:

The bash man page says that

For almost every purpose, shell functions are preferred over aliases

You’ll likely have a linter complaining about a positional parameter in an alias. And yes, I realize that the $1 here is an awk thing rather than a bash thing, but my linter doesn’t know that.

Having said that, how you handle this is entirely up to you. If someone tells that using an alias means you’re wrong, you can kindly tell them to get stuffed, because there’s certainly more than one way to do it.

How it Works
#

Let’s break this down. Basically there are 4 things happening here:

cd "$(git worktree list | fzf | awk '{print $1}')"

git worktree list is being called
All of the output from git worktree list is piped directly to fzf. At this point nothing happens until there is some input from the keyboard
Once there is a carriage <return>, the entire selected line is handed off to awk, which splits the line on spaces and returns the first element in the list ($1). That element is the path to the root directory of the worktree.
The worktree path is provided to the cd command and now you are on your way

Build Something Fun
#

What I like about this example is that it’s not particularly complicated, but it has enough moving parts that it merits some discussion. You could build something similar for switching between git branches, tmux sessions or something way better that I haven’t even thought of.

Because it fits on one line you can even keep it as a handy snippet that you copy/paste, if you don’t feel like making shell functions available or putting the one-liner into a script or whatever.

I hope you have fun with this. Please let me know if you build something you’d like to share with me.

Read on website

Getting Started with perlimports

Mon, 15 Apr 2024 10:00:00 +0000

A version of this post was previously published in the 2023 Perl Advent Calendar. I have significantly revised it for publication here.

What’s in a Package, Anyway?
#

Perl, like many other languages, exposes the functionality to export functions (and other things) from one package into another. The functions that are exported by package A are the same functions that are imported into package B. Consider the following code:

package WhereAmI;

use 5.38.0;

use Git::Helpers qw( checkout_root );

say checkout_root(); # or WhereAmI::checkout_root()

In this example, Git::Helpers is exporting the checkout_root function into WhereAmI. Conversely, WhereAmI is importing the checkout_root function from Git::Helpers. Importing and exporting are two sides of the same coin. The important thing to note is we now have a new function available in the WhereAmI package.

Today we’ll mostly be referring to imports, but in many cases we could just as well be framing our discussion in terms of exports instead.

What is perlimports?
#

I have been interested in code quality for many years. This is something I touched on in Find and Fix More Typos and Finding Unused Perl Variables. As part of that interest, I wrote a tool to help automate cleaning up cases where code is being imported. This tool is called perlimports. perlimports is a tidier, which means it can rewrite our code for us. It’s also a linter, so we can use it to report on problems without rewriting our code. With this power comes great responsibility. perlimports tries to be responsible.

Inspired by goimports, perlimports is an opinionated tool which tries to force its opinions onto our code. What we get in return is a tool which takes much of the burden of managing imports out of our hands.

If you’re interested in a more thorough discussion of how perlimports and Perl’s use and require work, I spoke about this in depth at The Perl Conference in 2021: perlimports or “Where did that symbol come from?”.

Why Tidy Imports at all?
#

You may quite correctly be asking yourself if perlimports is worth the bother. Why even bother? After having used this tool in anger for about 3 years now, I’ll try to sum up the best points.

Consistent Style
#

Just like any other tidier, using perlimports will automate and enforce a consistent style for your imports. This has the following advantages:

Code is Easier to Read
#

When your imports are laid out in a consistent manner, your code can become easier to scan. You’ll have consistent spacing, the imports for a given module will be alpha-sorted and you’ll have a standard quoting style. This should reduce the cognitive load when you’re looking at the first few lines of your files.

Diffs Become Easier to Read
#

Once code layout is consistent, code changes can become easier to read, since you’re less likely to be confronted with formatting changes. This can also reduce the size of your diffs, which also reduces cognitive load.

Code Reviews are Easier
#

Hopefully code reviewers will no longer have to comment on how someone used the wrong quotes or how they imported something they’re not actually using. If your linting and tidying is automated, code contributors can now also stop worrying about these little things.

Writing Code is Less Onerous
#

Once you have a tidier to do the work for you, you can be a fair bit sloppier when writing code. Write it quickly, get it out of your system and then tidy the file and watch the magic happen. Not having to worry about the mundane frees up mental energy for other things.

Improved Dependency Management
#

Once you start automatically removing from your code the imports (and even the modules) which you are not using, it should be easier for you to evaluate which dependencies you actually need. You may find that you’ve been installing modules which you don’t actually use. Fewer dependencies leads to a better security posture (since you’ve reduced your attack surface), faster setup time (because you now have fewer things to install) and fewer headaches around not being to install this or that module in a certain environment. Dependencies are great when you need them, but limiting your dependencies can also have some real benefits. Unfortunately, linting Perl’s imports is not always as easy as we’d like. Let’s try to contextualize the problem by taking a quick look at the tools module authors might use to export code into yours.

There’s More Than One Way to Do It
#

If you’ll allow a small digression, Perl’s import() is an incredibly powerful tool that does little in the way of imposing restrictions on the implementor when it is run. This means that over the years CPAN authors have allowed themselves to be very creative when it comes to what may or may not get imported into our code.

This liberal approach to code import has also allowed for the proliferation of modules which authors can use to manage what their code exports into ours.

This is not an exhaustive list, but it’s also the kind of TIMTOWTDI that might leave a Perl newbie scratching their head in confusion and wonder.

The upshot of all of these different methods of exporting is that a static code analysis is not an effective way of discovering what is being imported into your code. perlimports needs to eval the package imports and then (in many cases) see what actually changed in the symbol table. This means two things:

We need to install dependencies and be able to eval them in order to see what’s going on
A speed penalty is imposed on perlimports for this approach

Strategy
#

As we saw above, there is an embarrassment of riches when it comes to modules to manage code exports. Some of these exporters work in very different ways, which makes the job of perlimports tricky. If we accept that it can be difficult to predict what some code is actually importing, we will probably want to be very careful when rewriting imports. The more “important” the code is, the more careful we’ll want to be. perlimports makes a best effort, but it simply cannot be correct in every case.

I find that a good approach is to start with lower impact code and move on from there, once we’ve established that we’re on a good path. For example, we could first run perlimports as a linter, just to see what it might change. Or we could get some code which is under version control and run perlimports as a tidier on it and just diff the code to see what has changed.

I would probably start by applying perltidy to the test suite (assuming it exists) and then running the tests to see what the impact is. From there I might move to some code which has good test coverage. Eventually I would make my over to other code which is lacking in coverage and/or is harder to unit test. Working from lower to higher impact code allows for a gentle introduction of our new linting and tidying tool. We’ll explore this approach in more detail below, after we cover installation.

Installation
#

Let’s take a look at a typical getting started workflow. First we’ll install the package from CPAN. I like to use https://metacpan.org/pod/App::cpm, but feel free to use your CPAN installer of choice:

 cpm install -g App::perlimports

(If you’re using https://github.com/tokuhirom/plenv to manage your Perl installations, don’t forget to run plenv rehash after cpm install.)

Once that is done, we are ready to try perlimports. The quick way to run it on a new repository might look something like this:

Getting Started
#

Clone a repo
Install *all* of the repository’s dependencies (including recommended)
Run the test suite
Ensure all of the tests are passing. If there are test failures, fix those first
Run perlimports with the --lint flag to see what changes it might make
Tweak the configuration until we’re happy with the linting results
Apply perlimports to the tests. We can do this via perlimports -i t
Ensure all of the tests are still passing
Commit the changes
Move on to other parts of the code, e.g.: perlimports -i lib

In a best case scenario, this “just works”. Let’s try it on a really old repository of mine.

$ git clone https://github.com/oalders/acme-odometer.git
$ cd acme-odometer/
$ cpm install -g --with-recommends --cpanfile cpanfile
$ yath t
$ perlimports --lint t

I’m not including the command output, but I ran this locally and all of the steps “just worked”. I ran the test(s) via yath and they passed. Why did I use yath rather than make test or prove? I certainly could have done either of those things, but I’m trying to get in the habit of using more modern tools. yath comes bundled with Test2::Harness. If you’d like to learn more about some of the features which Test2 provides, please see Santa’s Workshop Secrets: The Magical Test2 Suite (Part 1) and Santa’s Workshop Secrets: The Magical Test2 Suite (Part 2).

Now, let’s see what the linting looks like:

$ perlimports --lint t
❌ Test::Most (import arguments need tidying) at t/load.t line 1
@@ -1 +1 @@
-use Test::Most;
+use Test::Most import => [ qw( done_testing ok ) ];

❌ Acme::Odometer (import arguments need tidying) at t/load.t line 3
@@ -3 +3 @@
-use Acme::Odometer;
+use Acme::Odometer ();

❌ Path::Class (import arguments need tidying) at t/load.t line 4
@@ -4 +4 @@
-use Path::Class qw(file);
+use Path::Class qw( file );

We can see three suggestions have been made. In the first suggestion, perlimports has detected that done_testing and ok are the only functions exported by Test::Most which the test is using, so it has made this explicit.

In the second suggestion perlimports has detected that the test is not importing any symbols from Acme::Odometer, so it has made this explicit by adding the empty round parens following the use statement.

In the third suggestion we see that some whitespace padding has been added to the Path::Class import.

If we don’t like these changes, we can tweak the configuration. To tell perlimports to ignore Test::Most, we can change our incantation:

perlimports --lint --ignore-modules Test::Most t

If we also don’t like the additional padding, we can turn that off:

perlimports --lint --ignore-modules Test::Most --no-padding t

Applying these settings we now get:

$ perlimports --lint --ignore-modules Test::Most --no-padding t
❌ Acme::Odometer (import arguments need tidying) at t/load.t line 3
@@ -3 +3 @@
-use Acme::Odometer;
+use Acme::Odometer ();

It’s time to update the actual file. We’ll use -i for an inplace edit:

perlimports -i --ignore-modules Test::Most --no-padding t

The result is:

git --no-pager diff t
diff --git a/t/load.t b/t/load.t
index 503d560..d19688f 100644
--- a/t/load.t
+++ b/t/load.t
@@ -1,6 +1,6 @@
 use Test::Most;

-use Acme::Odometer;
+use Acme::Odometer ();
 use Path::Class qw(file);

 my $path = file( 'assets', 'odometer' )->stringify;

Are the tests still passing?

yath t

** Defaulting to the 'test' command **

( PASSED ) job 1 t/load.t

                                Yath Result Summary
-----------------------------------------------------------------------------------
     File Count: 1
Assertion Count: 3
      Wall Time: 1.00 seconds
       CPU Time: 1.42 seconds (usr: 0.32s | sys: 0.09s | cusr: 0.77s | csys: 0.24s)
      CPU Usage: 142%
    --> Result: PASSED <--

Excellent. Let’s add the changes via git and commit them. After that, let’s turn to the lib directory.

$ perlimports --lint --ignore-modules Test::Most --no-padding lib
❌ namespace::clean (appears to be unused and should be removed) at lib/Acme/Odometer.pm line 9
@@ -9 +8,0 @@
-use namespace::clean;

❌ GD (import arguments need tidying) at lib/Acme/Odometer.pm line 11
@@ -11 +11 @@
-use GD;
+use GD ();

❌ Memoize (import arguments need tidying) at lib/Acme/Odometer.pm line 12
@@ -12 +12 @@
-use Memoize;
+use Memoize qw(memoize);

❌ Path::Class (import arguments need tidying) at lib/Acme/Odometer.pm line 14
@@ -14 +14 @@
-use Path::Class qw( file );
+use Path::Class qw(file);

Now, we already see some issues. First off, perlimports doesn’t seem to know about namespace::clean. That’s ok. We can ignore it.

perlimports --lint --ignore-modules namespace::clean,Test::Most \
 --no-padding lib

As an aside, we could also update the code to use namespace::autoclean while we’re poking around, but we’re trying to make minimal changes in this first iteration.

The last suggestion is to remove the padding from the Path::Class imports. It’s good to be consistent. The second and third suggestions look to be solid. Let’s make this change.

perlimports -i --ignore-modules namespace::clean,Test::Most --no-padding lib

That gives us:

$ git --no-pager diff lib
diff --git a/lib/Acme/Odometer.pm b/lib/Acme/Odometer.pm
index 7fee773..cb1734e 100644
--- a/lib/Acme/Odometer.pm
+++ b/lib/Acme/Odometer.pm
@@ -8,10 +8,10 @@ package Acme::Odometer;
 use Moo 1.001;
 use namespace::clean;

-use GD;
-use Memoize;
+use GD ();
+use Memoize qw(memoize);
 use MooX::Types::MooseLike::Numeric qw(PositiveInt PositiveOrZeroInt);
-use Path::Class qw( file );
+use Path::Class qw(file);

That’s pretty good. Do the tests still pass? Yes, they do. So, we can commit this change as well. Not every introduction of perlimports will be this easy, but it’s nice to start off with a win. Can we improve our experience? I think so. Paring down our use of the command line switches would be a good start. We can do that via a config file.

A Configuration File
#

Aside from just running perlimports with fewer switches at the command line, what if we wanted to run perlimports via the Perl Navigator Language Server? It would be better if we didn’t have to worry about the custom command line switches there as well. This sounds like a good time to create a config file.

perlimports --create-config-file perlimports.toml

Nice! We have a stub configuration file. Let’s see what’s inside perlimports.toml

# Valid log levels are:
# debug, info, notice, warning, error, critical, alert, emergency
# critical, alert and emergency are not currently used.
#
# Please use boolean values in this config file. Negated options (--no-*) are
# not permitted here. Explicitly set options to true or false.
#
# Some of these values deviate from the regular perlimports defaults. In
# particular, you're encouraged to leave preserve_duplicates and
# preserve_unused disabled.

cache = false # setting this to true is currently discouraged
ignore_modules = []
ignore_modules_filename = ""
ignore_modules_pattern = "" # regex like "^(Foo|Foo::Bar)"
ignore_modules_pattern_filename = ""
libs = ["lib", "t/lib"]
log_filename = ""
log_level = "warn"
never_export_modules = []
never_export_modules_filename = ""
padding = true
preserve_duplicates = false
preserve_unused = false
tidy_whitespace = true

Let’s commit the stub file to git and then let’s move our command line switches to the config file. The diff should look something like this:

$ git --no-pager diff perlimports.toml
diff --git a/perlimports.toml b/perlimports.toml
index d631998..1e54c9e 100644
--- a/perlimports.toml
+++ b/perlimports.toml
@@ -10,7 +10,7 @@
 # preserve_unused disabled.

 cache = false # setting this to true is currently discouraged
-ignore_modules = []
+ignore_modules = ["namespace::clean", "Test::Most"]
 ignore_modules_filename = ""
 ignore_modules_pattern = "" # regex like "^(Foo|Foo::Bar)"
 ignore_modules_pattern_filename = ""
@@ -19,7 +19,7 @@ log_filename = ""
 log_level = "warn"
 never_export_modules = []
 never_export_modules_filename = ""
-padding = true
+padding = false
 preserve_duplicates = false
 preserve_unused = false
 tidy_whitespace = true

We can iterate on this config file as we start tidying more of our code, but this is already an excellent start. Now we’re ready to start setting up editor integrations.

Neovim
#

nvim-lint
#

Users of Neovim can enable perlimports linting via https://github.com/mfussenegger/nvim-lint

Language Server Protocol (LSP)
#

Perl Navigator
#

If you’re using an editor with LSP support (like Neovim or VS Code), you can hopefully get perlimports running via the Perl Navigator Language Server. This language server has perlimports disabled by default, so we’ll need to switch it on in the configuration and also make sure that we have the perlimports binary installed and in our $PATH.

{
 perlimportsProfile = 'perlimports.toml',
 perlimportsLintEnabled = true,
 perlimportsTidyEnabled = true,
}

In addition to editor configuration, we can now think about adding perlimports to our Continuous Integration and pre-commit hooks as well, so that we maintain the changes we’ve just imposed. We could do this via precious.

The Power of precious
#

I talked about using Code::TidyAll in How Santa’s Elves Keep their Workshop Tidy. tidyall is a wonderful tool that solves a lot of problems, but its design was not perfect and it’s looking for a new maintainer. In the meantime, precious has drawn inspiration from tidyall and can be regarded as its spiritual successor, even if it’s written in Rust. If we want to run perlimports along with other fixing and linting tools, we can use precious for this.

We won’t cover installation here, but after installing precious we can generate a stub config file:

$ precious config init --component perl

Writing precious.toml

The generated precious.toml requires the following tools to be installed:
  https://metacpan.org/dist/Perl-Critic
  https://metacpan.org/dist/Perl-Tidy
  https://metacpan.org/dist/App-perlimports
  https://metacpan.org/dist/Pod-Checker
  https://metacpan.org/dist/Pod-Tidy

Let’s have a look at the created file:

excludes = [
    ".build/**",
    "blib/**",
]

[commands.perlcritic]
type = "lint"
include = [ "**/*.{pl,pm,t,psgi}" ]
cmd = [ "perlcritic", "--profile=$PRECIOUS_ROOT/perlcriticrc" ]
ok_exit_codes = 0
lint_failure_exit_codes = 2

[commands.perltidy]
type = "both"
include = [ "**/*.{pl,pm,t,psgi}" ]
cmd = [ "perltidy", "--profile=$PRECIOUS_ROOT/perltidyrc" ]
lint_flags = [ "--assert-tidy", "--no-standard-output", "--outfile=/dev/null" ]
tidy_flags = [ "--backup-and-modify-in-place", "--backup-file-extension=/" ]
ok_exit_codes = 0
lint_failure_exit_codes = 2
ignore_stderr = "Begin Error Output Stream"

[commands.perlimports]
type = "both"
include = [ "**/*.{pl,pm,t,psgi}" ]
cmd = [ "perlimports" ]
lint_flags = ["--lint" ]
tidy_flags = ["-i" ]
ok_exit_codes = 0
expect_stderr = true

[commands.podchecker]
type = "lint"
include = [ "**/*.{pl,pm,pod}" ]
cmd = [ "podchecker", "--warnings", "--warnings" ]
ok_exit_codes = [ 0, 2 ]
lint_failure_exit_codes = 1
ignore_stderr = [
    ".+ pod syntax OK",
    ".+ does not contain any pod commands",
]

[commands.podtidy]
type = "tidy"
include = [ "**/*.{pl,pm,pod}" ]
cmd = [ "podtidy", "--columns", "80", "--inplace", "--nobackup" ]
ok_exit_codes = 0
lint_failure_exit_codes = 1

We can see that the config already includes a linting and tidying configuration for lots of helpful Perl linters and tidiers, including perlimports. Now, we can run precious tidy --all or precious lint --all to run all sorts of checks in pre-commit hooks and other places where code quality needs to be ensured.

precious is a powerful tool and it merits its own blog post, but let’s leave this as a quick introduction. Perhaps you’ll feel inspired to try it out.

That’s a Wrap
#

I currently have some capacity in my schedule for client work. If you or your team need help with Perl dependency management and/or integrating perlimports, precious and other code quality tools into your environment, I’m available for hire.

We’ve covered a lot of ground here today. If you have any comments or suggestions for improvements, please do reach out to me. I’d love to hear from you.

Read on website

GitHub Copilot Chat: First Impressions

Thu, 29 Feb 2024 00:00:00 -0500

Recently I got access to GitHub’s Copilot Chat. I had seen a demo of it back in December and was very impressed with what it can do. Since getting access, I have been trying to figure out how (and if) Copilot can help to improve my productivity.

Nota bene: This article is not an advertisement for AI. I am aware of many of the caveats when it comes to AI, but in the short term I am interested in seeing how I can get a genuine positive result from it.

Initially I did not think yet another article on AI would have any point. If you read Hacker News, you may be of the opinion that everyone is using AI already, but that’s not the case. Many smart, competent software developers do not use AI (yet?). Some of them may not be aware of how they can leverage AI and some may simply be wary of all the hype.

My plan is to share some practical examples. This won’t be a “how to” article, but rather a higher level overview of what might be possible. I won’t be going into details about exactly which prompts I used to get my results. I will leave that as an exercise for the reader. It is my hope that I’ll give you enough information that you can judge for yourself if it is worth your time to play around with this.

My Setup
#

I have been using Copilot for completion for a few months now. My setup is neovim + nvim-cmp with the following plugins:

That mostly works for me. Sometimes the completion is a bit funky. Opening up related files to give Copilot more context is helpful. For me, Copilot is a net positive, but it can be a bit of a slog sometimes.

In order to use Copilot Chat, I opted to set up VS Code with the following plugins:

GitHub Copilot
GitHub Copilot Chat

This means that I need to live in VS Code when using Copilot’s Chat features. This is not ideal, but so far I accept the trade-off as necessary and I am not grumbling about it. I am still in neovim when VS Code is not required, but with all of the file reloading, they are playing nicely together for the most part.

I should note that CopilotC-Nvim/CopilotChat.nvim does exist. I haven’t tried it as I wanted to get up and running in a hurry. neovim purists may prefer it.

Building a New Jekyll Site
#

As you may be aware, I am looking to pick up some freelance work right now. I have had some success, but there is still room in my schedule. I have not actively looked for work in some time. My web site did not look very modern and the listed skill set was dated – I have not written an iOS app in years.

My site was deployed using a web application framework, but I no longer need to do anything dynamic. Time to find a static site generator. Jekyll is a very mature site builder with lots of available themes, so I started there.

First, I settled on a theme.

I like the look of it. It has a lot of GitHub stars and a small number of open issues and pull requests. I extrapolate wildly from this that people are using it and not having a great deal of problems. That’s good enough for right now. It’s going to be a huge improvement.

Installing rbenv
#

I needed ruby to run my Jekyll build locally. I’ll want to be able to edit my site on more than one machine, so I quickly wrote an installer script to install rbenv if needed and then to install an arbitrary version of ruby if needed. I used is, which is a command line tool which I recently wrote. I am quite happy with how simple and readable this script turned out to be. If you’re curious about is, I have written an introduction to is not so long ago.

Replacing Google
#

As I was exploring what I needed to do, I used Copilot Chat as a Google replacement, asking it the kind of things I normally would have searched Google for. That went very well. I got good information without having to wade through a top result from W3Schools followed by lots of mediocre Medium posts and dated StackOverflow answers.

Using Copilot as my search engine has the added benefit of not requiring me to leave my editor. Once the response has been generated, being able directly to replace code with Copilot’s suggestion is a nice little productivity feature as well.

Aside from not needing Google for good information about how to set up Jekyll, I have found Copilot to be powerful when doing mundane things like scaffolding config files. I can say something like “Give me a best practice eslint configuration” and I might see an answer like this:

{
 "env": {
 "browser": true,
 "es6": true,
 "node": true
 },
 "extends": ["eslint:recommended", "plugin:react/recommended"],
 "globals": {
 "Atomics": "readonly",
 "SharedArrayBuffer": "readonly"
 },
 "parserOptions": {
 "ecmaFeatures": {
 "jsx": true
 },
 "ecmaVersion": 2018,
 "sourceType": "module"
 },
 "plugins": ["react"],
 "rules": {
 "indent": ["error", 2],
 "linebreak-style": ["error", "unix"],
 "quotes": ["error", "double"],
 "semi": ["error", "always"],
 "no-console": "warn",
 "no-unused-vars": "warn"
 },
 "settings": {
 "react": {
 "version": "detect"
 }
 }
}

We can argue about whether or not this really is best practice, but I do not have strong opinions on this. At the end of the day I just want code that is consistent and this gives me a starting point, since it’s in my nature to fiddle with settings. Also, VS Code tells me what the config file should be called. That may seem trivial but on more than one occasion I have struggled with figuring out why some tool is not working only to realize the file needed to start with a dot.

Looking back on this, I could have refined the prompt to say that I’m not using React, which should have pared down the file a bit, but for an 80/20 approach where I try to get the main things done now and I get to fiddle with it later, superfluous settings in a config file aren’t going to keep me up at night.

Front End Design
#

As I was working on the layout, I asked Copilot for help in tweaking the layout. It helpfully gave me advice and generated CSS to go with it.

Asset Upgrades
#

As I took a closer look at the theme, I saw that some included assets were very old.

Bootstrap (3.2.0, released in June 2014)
jQuery (1.11.0 from January 2014)

Everything still worked, but this seemed like a fun chance to experiment with Copilot. Could it do the right thing or would I be stuck in a world of find and replace? Time to find out. I upgraded the Bootstrap assets and asked Copilot to upgrade the CSS usage to Bootstrap 5. To my surprise, that mostly just worked.

As for jQuery, I asked Copilot to convert it to pure JavaScript. That worked very well, requiring very little intervention from me. I even eliminated a 3rd party library in the process. jQuery was not bringing much to the table here and I was able to eliminate a pretty large dependency. So far, so good.

Asset Creation
#

I then used Microsoft Image Creator to come up with some artwork.

Again I was quite happy with the result. The image creation has some limitations. It seems to want to give me blue eyes, even when I ask for brown. It also makes my White Shepherd look more like a Husky, but that feels like quibbling. In real life she often gets called a Husky, occasionally even by Husky owners.

Responsive Design
#

The only remaining issue was that the layout did not work consistently across various device resolutions. Copilot could not help me with this, partly because I lacked the vocabulary to describe the problem. Luckily a very generous friend gave me the help that I needed to get this little problem sorted out.

The End Result
#

Over a few hours on a Saturday and Sunday, I was able to switch to a brand new site, run by a static site generator. When I push my commits, the Jekyll site rebuilds and publishes via GitHub pages. It all requires very little intervention from me. As someone who does a bit of web hosting, it might seem weird that I am not dogfooding my web site, but at this point in my career I am more interested in the right tools for the right job. Occasionally I enjoy an overly complicated hobby project, but this aint it.

Lessons Learned
#

Now that I’ve used AI to kick start a rapid web site replacement, what have I learned?

Trust, but Verify
#

Copilot will tell you things with such confidence that it can be jarring when it is clearly wrong. I recently gave Copilot a bit of Ansible config which updates a system configuration file. I asked for this to be converted to an equivalent bash one-liner. Copilot was more than happy to do this. The caveat was that the resulting code was set up to blow away the original multi-line system file and replace it with the one line I was trying to add. I did not get caught by this bit of misinformation, but caveat emptor.

I haven’t been using Copilot in anger on really gnarly or convoluted code. Copilot cannot get context from all of the code in a really large project. The bigger and more complicated your project is, the greater the possibility that you’ll get less than helpful output from Copilot. Just as you would not blindly copy/paste a StackOverflow answer into production code, you don’t want to ship Copilot suggestions without proper scrutiny.

Copilot Can Tidy Things that Tidiers Possibly Can’t
#

I love tidiers and tidying. I talked about this a bit in my post about typos. I have long been frustrated by the lack of tidiers which are template-aware. Copilot did a great job of respecting Jekyll template syntax when I asked it to reformat the HTML in the files. I am hopeful it is equally good at Go and Perl HTML templates. Even if it is currently not, I am confident that this is on the horizon.

Mundane Tasks Become Less Soul-crushing
#

I recently wrote two Playwright tests in TypeScript which were largely similar, but with important, subtle differences. Copilot not only refactored these to allow them to share common code, but it actually created table-driven tests for me. The result was so much cleaner and more maintainable than what I had started with. The practical benefit is that I hope I am in a position where I do not always have to write code with the inevitable refactor in mind. I liken this to the fact that I rarely format my own code these days. I just write something that’s mostly readable and I rely on a tidier to enforce style.

The wider implication is that if I am asked, in the parameters of a code review, to do some tedious task that I really do not want to do because “why are you asking me now when you could have saved me a bunch of time by mentioning this earlier”, I can ask Copilot to implement the request for me. If it works, everybody wins. If it does not, then I still have the choice to punt on the change if I think it can wait or to dig in and try to refactor the code myself.

What that means to me is not having to spend mental energy on things that do not matter that much. I can lose a lot of time dealing with code review nitpicks that I often do not have the energy to argue against. Now I have a chance to see if my new toy can implement the request for me.

Legacy Projects Get New Life
#

I recently realized that the landing page for the Perl Advent Calendar looked quite dated. If you looked at it you would be forgiven for thinking the calendar was possibly abandoned. We published a full calendar of articles in 2023 and 2022, so it’s anything but abandoned.

I asked Copilot to modernize the design and it did so quite happily, giving me a workable result on the first try. I then asked it to add some JavaScript to redirect to a different page in December and January of any given year. These are all things which I could have done myself, but I did not want to.

You can argue that this kind of work isn’t hard. It’s not really, but it was onerous enough that nobody did it for many years. I liken this to taking on a task myself or having an intern do it. If the intern does it, I still need to explain the problem and check the work, but it frees me up to do something else in the meantime. If the intern is effective, it’s a time saver. If the intern needs a lot of help, then I haven’t gained much at all. I need to figure out what the intern can handle and then assign appropriate tasks.

With refactoring and modernising of code becoming easier to handle, the burden of maintenance decreases. Perhaps projects which have fallen into disrepair can more easily be revived.

Creating Tabular Content
#

I love Markdown tables, but boy do I not enjoy creating them. Let’s try it with Copilot.

Create a markdown table of the names of the 12 months of the year. Each row represents one month. The columns are the month names in Latin, Italian, Spanish, French and German

Suprisingly, we get what we asked for.

| Latin | Italian | Spanish | French | German |
| ---------- | --------- | ---------- | --------- | --------- |
| Ianuarius | Gennaio | Enero | Janvier | Januar |
| Februarius | Febbraio | Febrero | Février | Februar |
| Martius | Marzo | Marzo | Mars | März |
| Aprilis | Aprile | Abril | Avril | April |
| Maius | Maggio | Mayo | Mai | Mai |
| Iunius | Giugno | Junio | Juin | Juni |
| Iulius | Luglio | Julio | Juillet | Juli |
| Augustus | Agosto | Agosto | Août | August |
| September | Settembre | Septiembre | Septembre | September |
| October | Ottobre | Octubre | Octobre | Oktober |
| November | Novembre | Noviembre | Novembre | November |
| December | Dicembre | Diciembre | Décembre | Dezember |

Will we double-check the spelling before using this in anger? You bet we will, but if we had typed this by hand we would have checked it anyway.

If we want this table in HTML, we say “convert the table to HTML” and it is done. Likewise, we can ask for a CSV:

"Latin","Italian","Spanish","French","German"
"Ianuarius","Gennaio","Enero","Janvier","Januar"
"Februarius","Febbraio","Febrero","Février","Februar"
"Martius","Marzo","Marzo","Mars","März"
"Aprilis","Aprile","Abril","Avril","April"
"Maius","Maggio","Mayo","Mai","Mai"
"Iunius","Giugno","Junio","Juin","Juni"
"Iulius","Luglio","Julio","Juillet","Juli"
"Augustus","Agosto","Agosto","Août","August"
"September","Settembre","Septiembre","Septembre","September"
"October","Ottobre","Octubre","Octobre","Oktober"
"November","Novembre","Noviembre","Novembre","November"
"December","Dicembre","Diciembre","Décembre","Dezember"

Of course you can already do this with bash/sed/awk/jq or what have you, but not everyone views command line data transformation as a rewarding hobby. Now you have the option of getting arbitrary tabular data just by asking for it. It’s one more tool in your toolbox.

Code Review
#

Looking to the future, I see how Copilot could be useful when it comes to code reviews.

Ask Copilot to Explain Code
#

If I check out the branch I am reviewing and select some code with a language feature I do not quite understand, I can ask Copilot to explain it to me. (If I am asking it to explain some convoluted code, that’s a red flag for the review, but it can still help me get from A to B). I see this as potentially a significant time saver, but not a replacement for an in depth review by a human.

The same pattern can be applied to SQL. If you’re dealing with a lot of nested subqueries, CTEs (Common Table Expressions) or someone who treats SQL as their favourite programming language, then Copilot can help you untangle the logic. It’s no replacement for trying to understand the code yourself and it’s not always going to be 100% correct, but it’s nice as a second opinion. I expect this functionality will also improve with time.

Ask Copilot to Suggest Improvements
#

On a similar note, I can select some code and ask Copilot to suggest improvements. This may bring up some points which I had not previously considered. Again, it is not a replacement for the human review, but I imagine this could find issues which may get glossed over otherwise, based on who is reviewing the code.

Taking this one step further, I can ask Copilot for code suggestions before submitting my own code for review. This can catch issues before we start the code review feedback loop. The more I can prevent a lot of back and forth in a code review, the better placed I am to get it merged quickly. So this could be a time saver as well.

Improve Copy
#

Copilot can suggest improvements to documentation or even plain web site copy. When I tried this it, the suggestions were a clear improvement, turning awkward turns of phrase into something more easily readable. This can be useful in the proofreading phase, especially for non-native English speakers. (I have no idea how it performs in other languages.) I do often come across technical blog posts where the author’s language skills get in the way of the point they are trying to make. This could be a very useful tool in that case.

That’s a Wrap
#

There is a lot of concern about the explosion of AI and I think that these discussions are generally good to have, even if I am not going to get into that here. As far some of my other successful experiments, there are sill a number I did not even get to today. One of my most positive experiences has been with using AI to sell items on Kijiji, but there is too much to explore there. Maybe that’s a subject for another day.

If you’ve made it this far, thanks for sticking with me on this meandering journey – it has been an enjoyable ride.

Read on website

Find and Fix More Typos

Tue, 06 Feb 2024 00:00:00 +0000

This is a revised and expanded version of a post which originally appeared in the 2023 Perl Advent Calendar.

"Typewriter Eraser, Scale X" by ChrisYunker is licensed under CC BY 2.0 .

When you’re constantly producing code and documentation, mistakes will happen. Some will be easy to spot and others may elude you. We know that attention to detail counts. When someone finds a typo in your documentation or your code, they may be inclined to ask themselves what else may be wrong. In order to avoid the impression of carelessness, let’s automate the finding and fixing of typos.

The Tool
#

One of the tools which we have in our toolkit is the typos utility. The wonderful thing about typos is that this Rust-based tool can improve code and documentation in many different languages. It’s that good!

How it Works
#

From the docs:

typos maintains a list of known typo corrections to keep the false positive count low so it can safely run unassisted.

This is in contrast to most spell checking UIs people use where there is a known list of valid words. In this case, the spell checker tries to guess your intent by finding the closest-looking word. It then has a gauge for when a word isn’t close enough and assumes you know best. The user has the opportunity to verify these corrections and explicitly allow or reject them.

Getting Set Up
#

After installing typos, it’s trivial to spot typos in code.

 $ typos
[some output appears]

That’s it! Now, let’s try it on the Perl Advent Calendar. We’ll start with the articles in 2019. This gives us all sorts of helpful information.

$ typos 2019
 error: `entires` should be `entries`
 --> 2019/articles/2019-12-16.pod:253:23
 |
 253 | And start adding todo entires:
 | ^^^^^^^
 |
 error: `hightlight` should be `highlight`
 --> 2019/articles/2019-12-14.pod:113:56
 |
 113 | # work out the three strings (left of / before hightlight,
 | ^^^^^^^^^^
 |
 error: `hightlight` should be `highlight`
 --> 2019/articles/2019-12-14.pod:114:24
 |
 114 | # the middle / hightlight, and then right of / after highlight)
 | ^^^^^^^^^^
 |
 error: `assing` should be `assign`
 --> 2019/articles/2019-12-14.pod:121:27
 |
 121 | # what we want to assing to $x so we start drawing there again.

There are actually a few more typos, but this is a good demonstration of what we might find. Now, how do we fix it?

$ typos -w 2019

 error: `fils` should be `fills`, `files`, `file`
 --> 2019/articles/2019-12-20.pod:136:59
 |
 136 | if that machine can access the internet, if I can put the fils in my home
 | ^^^^
 |
 error: `whe` should be `when`, `we`
 --> 2019/articles/2019-12-19.pod:25:17
 |
 25 | between runs.", whe Wise Old Elf explained sagely, "Then you'd be able to
 | ^^^
 |

This actually fixes a number of typos, but there are two which the tool cannot resolve, so it makes some suggestions for us to use in a manual fix.

This leaves the matter of how many changes were actually made. Let’s see:

$ git diff --stat 2019
 2019/articles/2010-12-11.pod | 2 +-
 2019/articles/2019-12-04.pod | 2 +-
 2019/articles/2019-12-05.pod | 4 ++--
 2019/articles/2019-12-07.pod | 4 ++--
 2019/articles/2019-12-10.pod | 2 +-
 2019/articles/2019-12-12.pod | 2 +-
 2019/articles/2019-12-13.pod | 8 ++++----
 2019/articles/2019-12-14.pod | 6 +++---
 2019/articles/2019-12-16.pod | 2 +-
 2019/articles/2019-12-18.pod | 6 +++---
 2019/articles/2019-12-20.pod | 4 ++--
 2019/articles/2019-12-21.pod | 4 ++--
 2019/articles/2019-12-22.pod | 2 +-
 2019/articles/2019-12-24.pod | 2 +-
 14 files changed, 25 insertions(+), 25 deletions(-)

We can now go over the changes individually via git add -p and we’ll find that all but one seem to be correct. 24 typos found and fixed in 47 ms. That’s not bad at all.

As we process more and more files, we will likely find some false positives which we want to correct. This can be done in a config file. Ours is typos.toml.

[default.extend-words]
ANDed = "ANDed"
ba = "ba"
Claus = "Claus"
DNE = "DNE"
IFF = "IFF"
Signes = "Signes"

[files]
extend-exclude = ["advent.ini", "data.en"]

In order to skip false positives, we add words to the default.extend-words section. Yes, it’s kind of a surprising way to do this, but let’s go along with it. Also, any files which we don’t want to check can be added to extend-include in the [files] section.

Digging Deeper
#

Beyond the basics of typos and typos -w, we can do more. Let’s touch on a few things now, but you can always check typos --help for a more complete list of options.

`--words`
#

typos does its best to find words not only in your documentation, but also in your code. If you’re scratching your head as to why a certain word is not being flagged, you can use the --words flag to see a list of words in your project which are being checked. Maybe it’s not being discovered?

typos --words

To get a more readable list: typos --words | sort | uniq

To do some fuzzy matching on the list, pipe the results to fzf:

typos --words | sort | uniq | fzf

If you’re not familiar with fzf, you may find some of my fzf articles to be helpful.

`--locale`
#

Are you tired of typos telling you that the Queen’s (King’s?) English is wrong? You can change the locale to en-gb and you can once again feel at one with the universe.

The currently available locales are: en, en-au, en-ca, en-gb and en-us.

typos --locale en-gb

`--diff`
#

Would you like to see a diff before you run typos -w? You can do that via

typos --diff

Going back to our previous example:

typos --diff foo.pl
--- foo.pl original
+++ foo.pl fixed
@@ -3,2 +3,2 @@
-sub widht {}
-my $strng = 'foo';
+sub width {}
+my $string = 'foo';

Integrations
#

Neovim
#

Users of Neovim can also enable typos linting via https://github.com/mfussenegger/nvim-lint

VS Code
#

There is also a VS Code extension for typos. I’m not in VS Code very often, so I haven’t tested this myself, but that looks to be worth exploring.

LSP
#

If you prefer the Language Server Protocol (LSP), there is also an LSP integration, which is part of the VS Code extension above.

precious
#

If you use precious as a harness around your linters and tidiers, you can start by adding this to your configuration.

[commands.typos]
type ="both"
include = ["**/*"]
cmd = ["typos"]
tidy_flags = ["-w"]
ok_exit_codes = 0

If you haven’t tried precious, I highly recommend it. I’ll be digging a bit deeper into this tool in a forthcoming post. You may subscribe to email updates using the form at the bottom of this post, if you don’t want to miss it.

Now We Look Smart(er)
#

Having discovered this very useful tool, we can add it to our linters and fixers, make it part of our pre-commit hooks and include it in our Continuous Integration configuration.

For those of us who enjoy creating a quick pull request to fix someone else’s typos, we can now employ this tool on repositories which we have just checked out. A helpful pull request for a grateful maintainer 🙏 is just minutes away.

As one more data point, I used typos to check this very article and I’m both proud and ashamed to say that it found more than one problem. 😅

typos will not find all errors, but it will find issues which are hard for the human eye to spot. It’s not a replacement for a code review, but it’s a helpful tool to have in your toolbox for the days when you just don’t see the typos which are staring you in the face. The best part is, you get to find the typos before someone else does. 🥳

Read on website

Using Tig to Make Sense of Git

Wed, 17 Jan 2024 00:00:00 -0500

This article was originally published at opensource.com.

If you work with Git as your version control system, you’ve likely already resigned yourself to the fact that Git is a complicated beast. Git is a fantastic tool, but it can be cumbersome to navigate repositories, logs, the stash, etc. That’s where a tool like Tig comes in.

"Git icon" by Jason Long is licensed under CC BY 3.0 .

Related posts: I’ve also discussed Four Strategies for Context Switching in Git and Autocorrecting Git Commands.

From the Tig man page:

Tig is an ncurses-based text-mode interface for git(1). It functions mainly as a Git repository browser, but can also assist in staging changes for commit at chunk level and act as a pager for output from various Git commands.

This basically means that Tig provides a text-based user interface you can run in your terminal. Tig makes it easy to browse your Git logs, but it can do much more than just bounce you around from your last commit to a previous one.

default tig

Many of the examples in this quick introduction to Tig have been poached directly from its excellent man page. I highly recommend reading it to learn more.

Install Tig
#

Fedora and RHEL: sudo dnf install tig
Ubuntu and Debian: sudo apt install tig
MacOS: brew install tig

See the official installation instructions for even more options.

Browse commits in your current branch
#

If you want to browse the latest commits in your branch, enter:

tig

That’s it. This three-character command will launch a browser where you can navigate the commits in your current branch. You can think of it as a wrapper around git log.

To navigate the output, you can use the Up and Down arrow keys to move from one commit to another. Pressing the Return/Enter key will open a vertical split with the contents of the chosen commit on the right-hand side. You can continue to browse up and down in your commit history on the left-hand side, and your changes will appear on the right. Use k and j to navigate up and down by line and - and the Space Bar to page up and down on the right-hand side. Use q to exit the right-hand pane.

Searching on tig output is simple as well. Use / to search forward and ? to search backward on both the left and right panes.

commit tig

That’s enough to get you started navigating your commits. There are too many key bindings to cover here, but clicking h will display a Help menu where you can discover its navigation and command options. You can also use / and ? to search the Help menu. Use q to exit Help.

help tig

Browse revisions for a single file
#

Since Tig is a wrapper around git log, it conveniently accepts the same arguments that can be passed to git log. For instance, to browse the commit history for a single file, enter:

tig README.md

Compare this with the output of the Git command being wrapped to get a clearer view of how Tig enhances the output.

git log README.md

To include the patches in the raw Git output, you can add a -p option:

git log -p README.md

If you want to narrow the commits down to a specific date range, try something like this:

tig --after="2017-01-01" --before="2018-05-16" -- README.md

Again, you can compare this with the raw Git version:

git log --after="2017-01-01" --before="2018-05-16" -- README.md

Browse who changed a file
#

Sometimes you want to find out who made a change to a file and why. The command:

tig blame README.md

is essentially a wrapper around git blame. As you would expect, it allows you to see who the last person was to edit a given line, and it also allows you to navigate to the commit that introduced the line. This is somewhat like the :Gblame command Vim’s vim-fugitive plugin provides.

Browse your stash
#

If you’re like me, you may have a pile of edits in your stash. It’s easy to lose track of them. You can view the latest item in your stash via:

git stash show -p stash@{0}

You can find the second most recent item via:

git stash show -p stash@{1}

and so on. If you can recall these commands whenever you need them, you have a much sharper memory than I do.

As with the Git commands above, Tig makes it easy to enhance your Git output with a simple invocation:

tig stash

Try issuing this command in a repository with a populated stash. You’ll be able to browse and search your stash items, giving you a quick overview of everything you saved for a rainy day.

Browse your refs
#

A Git ref is the hash of something you have committed. This includes files as well as branches. Using the tig refs command allows you to browse all of your refs and drill down to specific commits.

tig refs

When you’re finished, use q to return to a previous menu.

Browse git status
#

If you want to view which files have been staged and which are untracked, use tig status, a wrapper around git status.

status tig

Browse git grep
#

You can use the grep command to search for expressions in text files. The command tig grep allows you to navigate the output of git grep. For example:

tig grep -i foo lib/Bar

will navigate the output of a case-insensitive search for foo in the lib/Bar directory.

Pipe output to Tig via STDIN
#

If you are piping a list of commit IDs to Tig, you must use the --stdin flag so that tig show reads from stdin. Otherwise, tig show launches without input (rendering an empty screen).

git rev-list --author=olaf HEAD | tig show --stdin

Add custom bindings
#

You can customize Tig with an rc file. Here’s how you can configure Tig to your liking, using the example of adding some helpful custom key bindings.

Create a file in your home directory called .tigrc. Open ~/.tigrc in your favorite editor and add:

# Apply the selected stash
bind stash a !?git stash apply %(stash)
# Drop the selected stash item
bind stash x !?git stash drop %(stash)

Run tig stash to browse your stash, as above. However, with these bindings in place, you can press a to apply an item from the stash to your repository and x to drop an item from the stash. Keep in mind that you’ll need to perform these commands when browsing the stash list. If you’re browsing a stash item, enter q to exit that view and press a or x to get the effect you want.

For more information, you can read more about Tig key bindings.

Wrapping up
#

I hope this has been a helpful demonstration of how Tig can enhance your daily workflow. Tig can do even more powerful things (such as staging lines of code), but that’s outside the scope of this introductory article. There’s enough information here to make you dangerous, but there’s still more to explore.

Read on website

4 Strategies for Context Switching in Git

Tue, 09 Jan 2024 00:00:00 +0000

"Control Panel switch module" by LogicalZero is licensed under CC BY-SA 2.0 .

This post was originally published at opensource.com

Anyone who spends a lot of time working with Git will eventually need to do some form of context switching. Sometimes this adds very little overhead to your workflow, but other times, it can be a real pain.

Related posts: I’ve also discussed Autocorrecting Git Commands and Using Tig to Make Sense of Git.

Let’s discuss the pros and cons of some common strategies for dealing with context switching using this example problem:

Imagine you are working in a branch called feature-X. You have just discovered you need to solve an unrelated problem. This cannot be done in feature-X. You will need to do this work in a new branch, feature-Y.

Solution #1: stash + branch
#

Probably the most common workflow to tackle this issue looks something like this:

Halt work on the branch feature-X
git stash
git switch -c feature-Y origin/main
Hack, hack, hack…
git switch feature-X or git switch -
git stash pop
Resume work on feature-X

Pros: The nice thing about this approach is that this is a fairly easy workflow for simple changes. It can work quite well, especially for small repositories.

Cons: When using this workflow, you can have only one workspace at a time. Also, depending on the state of your repository, working with the stash can be non-trivial.

Solution #2: WIP commit + branch
#

A variation on this solution looks quite similar, but it uses a WIP (Work in Progress) commit rather than the stash. When you’re ready to switch back, rather than popping the stash, git reset HEAD~1 unrolls your WIP commit, and you’re free to continue, much as you did in the earlier scenario but without touching the stash.

Halt work on the branch feature-X
git add -u (adds only modified and deleted files)
git commit -m "WIP"
git switch -c feature-Y origin/main
Hack, hack, hack…
git switch feature-X or git switch -
git reset HEAD~1

Pros: This is an easy workflow for simple changes and also good for small repositories. You don’t have to work with the stash.

Cons: You can have only one workspace at any time. Also, WIP commits can sneak into your final product if you or your code reviewer are not vigilant.

When using this workflow, you never want to add a --hard to git reset. If you do this accidentally, you should be able to restore your commit using git reflog, but it’s less heartstopping to avoid this scenario entirely.

Solution #3: new repository clone
#

In this solution, rather than creating a new branch, you make a new clone of the repository for each new feature branch.

Pros: You can work in multiple workspaces simultaneously. You don’t need git stash or even WIP commits.

Cons: Depending on the size of your repository, this can use a lot of disk space. (Shallow clones can help with this scenario, but they may not always be a good fit.) Additionally, your repository clones will be agnostic about each other. Since they can’t track each other, you must track where your clones live. If you need git hooks, you will need to set them up for each new clone.

Solution #4: git worktree
#

To use this solution, you may need to learn about git add worktree. Don’t feel bad if you’re not familiar with worktrees in Git. Many people get by for years in blissful ignorance of this concept.

What is a Worktree?
#

Think of a worktree as the files in the repository that belong to a project. Essentially, it’s a kind of workspace. You may not realize that you’re already using worktrees. When using Git, you get your first worktree for free.

$ mkdir /tmp/foo && cd /tmp/foo
$ git init
$ git worktree list
/tmp 0000000 [main]

As you can see, the worktree exists even before the first commit. Now, add a new worktree to an existing project.

Add a worktree
#

To add a new worktree, you need to provide:

A location on disk
A branch name
Something to branch from

$ git clone https://github.com/oalders/http-browserdetect.git
$ cd http-browserdetect/
$ git worktree list
/Users/olaf/http-browserdetect 90772ae [main]

$ git worktree add ~/trees/oalders/feature-X -b oalders/feature-X origin/main
$ git worktree add ~/trees/oalders/feature-Y -b oalders/feature-Y e9df3c555e96b3f1

$ git worktree list
/Users/olaf/http-browserdetect 90772ae [main]
/Users/olaf/trees/oalders/feature-X 90772ae [oalders/feature-X]
/Users/olaf/trees/oalders/feature-Y e9df3c5 [oalders/feature-Y]

Like with most other Git commands, you need to be inside a repository when issuing this command. Once the worktrees are created, you have isolated work environments. The Git repository tracks where the worktrees live on disk. If Git hooks are already set up in the parent repository, they will also be available in the worktrees.

Don’t overlook that each worktree uses only a fraction of the parent repository’s disk space. In this case, the worktree requires about one-third of the original’s disk space. This can scale very well. Once your repositories are measured in the gigabytes, you’ll really come to appreciate these savings.

$ du -sh /Users/olaf/http-browserdetect
2.9M

$ du -sh /Users/olaf/trees/oalders/feature-X
1.0M

Pros: You can work in multiple workspaces simultaneously. You don’t need the stash. Git tracks all of your worktrees. You don’t need to set up Git hooks. This is also faster than git clone and can save on network traffic since you can do this in airplane mode. You also get more efficient disk space use without needing to resort to a shallow clone.

Cons: This is yet another thing to remember. However, if you can get into the habit of using this feature, it can reward you handsomely.

A few more tips
#

When you need to clean up your worktrees, you have a couple of options. The preferable way is to let Git remove the worktree:

git worktree remove /Users/olaf/trees/oalders/feature-X

If you prefer a scorched-earth approach, rm -rf is also your friend:

rm -rf /Users/olaf/trees/oalders/feature-X

However, if you do this, you may want to clean up any remaining files with git worktree prune. Or you can skip the prune now, and this will happen on its own at some point in the future via git gc.

Notable notes
#

If you’re ready to get started with git worktree, here are a few things to keep in mind.

Removing a worktree does not delete the branch.
You can switch branches within a worktree.
You cannot, by default, simultaneously check out the same branch in multiple worktrees. If you do want to do this, you’ll need to use the --ignore-other-worktrees option when using git switch or git checkout. (Thanks to Linda O’Sullivan for this tip).
Like many other Git commands, git worktree needs to be run from inside a repository.
You can have many worktrees at once.
Create your worktrees from the same local checkout, or they will be agnostic about each other.

git rev-parse
#

One final note: When using git worktree, your concept of where the root of the repository lives may depend on context. Fortunately, git rev-parse allows you to distinguish between the two.

To find the parent repository’s root:
```
 git rev-parse --git-common-dir
```
To find the root of the repository you’re in:
```
 git rev-parse --show-toplevel
```

Choose the best method for your needs
#

As in many things, TIMTOWDI (there’s more than one way to do it). What’s important is that you find a workflow that suits your needs. What your needs are may vary depending on the problem at hand. Maybe you’ll occasionally find yourself reaching for git worktree as a handy tool in your revision-control toolbelt.

Read on website

is: an inspector for your environment

Wed, 27 Sep 2023 19:03:23 -0400

$ (is os name eq darwin && echo 🍏 ) ||
 (is os name eq linux && echo 🐧) ||
 echo 💣
$ 🍏

In a hurry? Jump straight to the README or install is now.

Motivation
#

Many years ago, before I switched to 100% remote work, I sat beside a young kid who had recently graduated from University. I picked up a lot of command line tricks from him, mostly by looking over his shoulder. I learned two big things from him:

vim is highly configurable
It’s helpful to keep your config files in a git repository

The kid had a neat way of organizing his stuff and by stuff I mean “dot files”. I copied some of his setup and, over the years, I have customized it a lot. My dot files get installed on Macs (sometimes with Apple silicon and sometimes not), Ubuntu VMs, Raspberry Pi and most recently on a Chromebook (so, Debian). I have different needs for different environments, but I want my dot files to handle as much of this as possible. Also, I’d like to keep them in public and on GitHub.

All this means that I have to do a few things to ensure everything gets installed in the right way and on the right machine.

So, you’re probably thinking that I just moved my dot files to Ansible configuration files.

I did not.

Right, but if I were sensible I would use one of the cool dot file frameworks to deploy to my various machines.

I did not.

Surely I’m not just using a bunch of bash scripts?

Yes, I am.

Now, this may not seem sensible to you, but my reasoning is:

I want the files to be installable everywhere and I want the repo to basically bootstrap itself, so if bash and git are available, things should mostly just work
I want my logic to run quickly, which can be hard to do with Ansible
I do not want to be constrained by someone else’s way of doing things
I do want to mess around with shell scripts
Don’t tell me what to do

Working within these parameters I’m able to do most of the things that I need to do, but some things seem hard. For instance “do A if we’re on a Mac but do B on Ubuntu (but only certain versions) or do B on Debian, but also certain versions. At some point doing all of this in bash feels kind of tedious. I wondered if I could write a tool to give me some of these answers in a more elegant way.

I eventually settled on Go as the implementation language for the tool and kong as the CLI arg parser. After messing around with kong, I realized that I could probably abuse commands and subcommands to come up with a CLI that reads (at least a little bit) like English. The end result is: is.

Recipes
#

Let’s dive right in.

Sometimes you don’t know if a binary is available. Let’s do a git clone only if git is available.

is there git && git clone https://github.com/oalders/is.git

Likewise, let’s install bat via homebrew, but only if we’re on a Mac.

is os name eq darwin && brew install bat

We could further expand this and only install via brew if it’s available:

is os name eq darwin && is there brew && brew install bat

Do we have a perl with a version >= 5.34 in our $PATH?

is cli version perl gte 5.34 && perl -E 'say "TIMTOWDI"'

Let’s express this by checking the minor version specifically:

is cli version perl --minor gte 34

Maybe we can support a range of versions:

is cli version perl --minor in 34,36,38

Just print the codename of this OS version:

$ is known os version-codename
ventura

Just print the system architecture:

$ is known arch
amd64

Try to upgrade ubi if it’s older than 7 days.

is cli age ubi gt 7 days && ubi --self-upgrade

Am I running as the correct user?

is cli output stdout whoami eq olaf

Is today Tuesday?

is cli output stdout date like Tue

Same, but without a regex:

is cli output stdout date --arg='+%a' eq Tue

Is today within Mon-Wed?

is cli output stdout date --arg='+%a' like 'Mon|Tue|Wed'

Same, but without a regex:

is cli output stdout date --arg='+%a' in Mon,Tue,Wed

Is this README.md greater than 800 lines long?

is cli output stdout 'bash -c' -a 'cat README.md|wc -l' gte 800

Are we on the main branch in this git repository?

is cli output stdout git --arg=branch --arg='--show-current' eq main

Check if git supports branch --show-current before running the previous command:

is cli version git gte 2.22 &&
 is cli output stdout git --arg=branch --arg='--show-current' eq main

Use a regex to match an SSH version. Note that ssh -V prints to STDERR.

is cli output stderr ssh --arg='-V' like 9.0p1

The above is essentially the same as the much shorter:

is cli version ssh like 9.0p1

Get the version of a CLI and do something with it.

$ version=$(is known cli version go) && echo $version
1.20.6

This is somewhat easier than parsing a version out of:

$ go version
go version go1.20.6 linux/amd64

In a script, exit early if it’s a Raspberry Pi.

if is os id eq raspbian; then
 exit 0
fi

At the command line, update the go binaries that vim-go needs:

is there go && nvim +:GoUpdateBinaries +qa

Same, but ensure nvim is installed:

is there go &&
 is there nvim &&
 nvim +:GoUpdateBinaries +qa

Same, but install plugins before :GoUpdateBinaries in order to ensure that vim-go has been installed:

is there go &&
 is there nvim &&
 nvim +:PlugInstall +:GoUpdateBinaries +qa

Same, but ensure we have at least version 1.20 of go:

is there go &&
 is cli version go gte 1.20 &&
 is there nvim &&
 nvim +:PlugInstall +:GoUpdateBinaries +qa

Now a more complex example. I want to install the nightly wezterm build. On macOS, I tend to use homebrew, but on Linux I’ve chosen to install the .deb files. To complicate the Linux example, I don’t want to re-install the nightly wezterm if I (for whatever reason) re-run my dot files installer. So, if wezterm has been installed within the last 18 hours, we won’t try installing it again. (See if is cli age wezterm lt 18 hours.)

The download URLs look like:

https://github.com/wez/wezterm/releases/download/nightly/wezterm-nightly.Ubuntu20.04.deb

and

https://github.com/wez/wezterm/releases/download/nightly/wezterm-nightly.Ubuntu22.04.deb

 1#!/usr/bin/env bash
 2
 3set -e -u -o pipefail
 4
 5install_for_linux() (
 6 sudo apt install -y libxcb-image0 libxkbcommon-x11-0
 7 version=$(is known os version)
 8 file=wezterm-nightly.${1}${version}.deb
 9
10 cd /tmp || exit 1
11 url=https://github.com/wez/wezterm/releases/download/nightly/$file
12 curl --location --output "$file" "$url"
13 sudo dpkg -i "$file"
14)
15
16if is os name eq darwin; then
17 if is there wezterm; then
18 brew upgrade homebrew/cask/wezterm
19 else
20 brew tap wez/wezterm
21 brew install --cask wezterm --no-quarantine
22 fi
23elif is os name eq linux; then
24 if ! is user sudoer; then
25 exit 0
26 fi
27 is there wezterm && is cli age wezterm lt 18 hours && exit
28 if is os id eq ubuntu && is os version in 20.04,22.04; then
29 install_for_linux Ubuntu
30 elif is os id eq debian && is os version --major in 10,11; then
31 install_for_linux Debian
32 fi
33fi

Hopefully this brief tutorial gives you an idea of what I had in mind with is. I wrote it entirely for my own needs. I’ve been living with it for a couple of months. For my purposes it has been just fine. Maybe you’ll find it useful as well.

Read on website

Closing Duplicate Tabs With AppleScript

Thu, 03 Aug 2023 20:47:54 -0400

"tab can" by lokate366 is licensed under CC BY-SA 2.0

ETOOMANYTABS
#

I have a browser tab problem. I open a lot of tabs in Chrome. I’m not great about closing them. To help me with my tab problem, I use Clutter Free. It prevents duplicate tabs from being opened. This works really well, but I can’t use this extension at $work.

At $work, I’m in an environment where I can only install Chrome extensions which have been approved by the org administrator. I could ask to get a new extension approved. It’s not a particularly onerous process, but I wondered if I could just script something to run on my Mac. That would allow me to solve the problem without a 3rd party Chrome extension.

In the past, I have copy/pasted AppleScript, but I don’t think I’ve ever written any from scratch. Maybe say "You look marvelous". That’s probably the extent of it.

I did, however, know that AppleScript can cycle through tabs. So, I came up with a plan to write some AppleScript that could cycle through all of the Chrome tabs on my Mac and close the duplicates. This solution doesn’t prevent duplicates from being opened, but it does close them after the fact and that mostly gets me to the same place.

I came up with the following:

#!/usr/bin/osascript

say "starting tab cleanup"
set urls to {}

tell application "Google Chrome"
 activate

 repeat with theWindow in every window
 set toClose to {}
 set tabIndex to 1
 repeat with theTab in every tab of theWindow
 set tabIsDuplicate to false
 repeat with seen in urls
 if (seen as string = URL of theTab as string) then
 copy tabIndex to the end of toClose
 set tabIsDuplicate to true
 exit repeat
 end if
 end repeat
 set tabIndex to tabIndex + 1

 if tabIsDuplicate is not true then
 copy URL of theTab as string to the end of urls
 end if

 end repeat

 set closing to reverse of toClose

 repeat with closeIndex in closing
 close tab closeIndex of theWindow
 end repeat
 set numberOfClosed to count of closing
 if numberOfClosed > 0 then
 say numberOfClosed
 say "tabs closed"
 end if
 end repeat
end tell
say "finished tab cleanup"

This brings Chrome to the forefront and cycles through each open Chrome window. For each window, it cycles through every tab. If the tab’s URL has already been seen, the script stores the tab number in a list of tabs we will need to close. Once all tabs in a window have been checked, we reverse the list of tab numbers that contain duplicate URLs and close them one by one. Then we move on to the next window and continue the process, until we run out of open windows.

You may ask yourself why we need to reverse the list of tab numbers before we close them? We do this because it makes it easier to avoid off-by-one errors. Let’s assume we need to close tabs 3, 5 and 7. Once we close tab 3, tabs 5 and 7 become tabs 4 and 6. We could handle this by decrementing those numbers, but if we just take the list in reverse this will never happen. For instance, with the 3, 5 and 7 scenario, when tab 7 has been closed, tabs 3 and 5 remain in the same position, so there is less state to keep track of.

Caveat Emptor
#

The script above will close tabs with extreme prejudice. So, if you’re doing something important in a duplicate tab or you wanted to close the first tab rather than the second, you’re out of luck. This suits my workflow fine, but maybe not yours.

Getting the Script
#

You can copy/paste the script directly from this post or download it from my dot files repo. It can be run directly at the command line. You can also run it via the Script Editor app, which comes with macOS. That’s handy for debugging.

Addendum
#

As a satisfied Hammerspoon user, I’ve added this script to my Hammerspoon config. That means I can now run my tab cleanup with a keyboard shortcut. In my case that’s caps lock + a. I won’t get into Hammerspoon configuration today, but my config file is on GitHub and large parts of it were stolen directly from Mark Fowler. It may be helpful to point out that I’m using Karabiner Elements to map caps lock to command+control+option+shift. That config is also on GitHub.

Read on website

Whither Perl

Wed, 19 Jul 2023 10:23:39 -0400

I recently spoke about the future of Perl at The Perl and Raku Conference. The slides are now available.

(Press the s key if you’d like to view the speaker notes for the slides.)

The video has been posted as well:

Correction
#

In the video I mentioned specifically learn.perl.org and assumed that it had no active ownership. I’ve now learned that *.perl.org is the property of the Perl NOC, who have owned and maintained these domains for decades. So, I’d like to thank them for their stewardship. Given this information, I’d like to retract my wish to fold these properties into perl.com. I do still think that learn.perl.org could use some updated information. Perhaps a learning section could be added to perl.com instead? It’s something to think about.

Read on website

Using Docker to Fix a Perl 5.37 Test Failure

Mon, 05 Jun 2023 00:00:00 +0000

"Tux and Docker" by maijo━ is licensed under CC BY-SA 2.0 .

It All Begins with a Bug
#

I recently got a bug report via GitHub that a test in Open::This is failing on Perl 5.37. Let’s take a look at it using gh:

 1gh issue view 48
 2t/open-this.t fails with perl 5.37.x #48
 3Open • eserte opened about 1 day ago • 0 comments
 4
 5
 6 I see the following test failure with recent bleadperls (maybe related to changed serialization of booleans):
 7
 8 # Failed test 'line 3'
 9 # at t/open-this.t line 167.
10 # +----+------------------------------------------------+------------------------------------------------+
11 # | Elt|Got |Expected |
12 # +----+------------------------------------------------+------------------------------------------------+
13 # | 0|{ |{ |
14 # | 1| file_name => 't/lib/Foo/Bar.pm', | file_name => 't/lib/Foo/Bar.pm', |
15 # * 2| is_module_name => !!1, | is_module_name => 1, *
16 # | 3| line_number => 3, | line_number => 3, |
17 # | 4| original_text => 'Foo::Bar::do_something()', | original_text => 'Foo::Bar::do_something()', |
18 # | 5| sub_name => 'do_something' | sub_name => 'do_something' |
19 # | 6|} |} |
20 # +----+------------------------------------------------+------------------------------------------------+
21 # Looks like you failed 1 test of 59.
22 t/open-this.t ..........
23 Dubious, test returned 1 (wstat 256, 0x100)
24 Failed 1/59 subtests
25
26
27View this issue on GitHub: https://github.com/oalders/open-this/issues/48

Although the layout of this blog makes it hard to see, the failure in question is on line 15. The test is expecting a value of 1 for the key is_module_name. However, under Perl 5.37 we get !!1 instead. As the ticket suggests, this looks like an issue with how booleans are represented in Perl 5.37. Since some permutation of Perl 5.37 will soon be released in production code as Perl 5.38, it’s a good idea to fix this test failure now. I asked for guidance on #toolchain on irc.perl.org and ilmari helpfully let me know that there are two options to fix this across Perl versions.

One option was to use Test2::Tools::Compare for the comparison. The other was to change the expected value in the test from 1 to !!1. I really like using Test::Differences, so I’m going to change the expected value.

I don’t have Perl 5.37 installed locally and because I’m in a hurry, I don’t want to use plenv to install it. Let’s use Docker instead, because that’s fairly quick and easy.

Sounds Like a Job for Docker
#

On host:

docker run -it --rm -v $PWD:/app perl:5.37 bash

This will drop you into a running Docker container. In the container itself, we can run the following commands.

cd /app && \
cpm install -g --cpanfile cpanfile && \
prove -lvr t

Alternatively, we can also do this without having to type in the container at all. The difference will be that our container will go away once the command has run to completion. This is handy for really quick things. On my machine it takes ~4 seconds once the Docker images have all been downloaded.

docker run -it --rm -v $PWD:/app \
perl:5.37 \
bash -c \
"cd /app && cpm install -g --cpanfile cpanfile && prove -lvr t"

The output I get is:

# Failed test 'line 3'
# at t/open-this.t line 167.
# +----+------------------------------------------------+------------------------------------------------+
# | Elt|Got |Expected |
# +----+------------------------------------------------+------------------------------------------------+
# | 0|{ |{ |
# | 1| file_name => 't/lib/Foo/Bar.pm', | file_name => 't/lib/Foo/Bar.pm', |
# * 2| is_module_name => !!1, | is_module_name => 1, *
# | 3| line_number => 3, | line_number => 3, |
# | 4| original_text => 'Foo::Bar::do_something()', | original_text => 'Foo::Bar::do_something()', |
# | 5| sub_name => 'do_something' | sub_name => 'do_something' |
# | 6|} |} |
# +----+------------------------------------------------+------------------------------------------------+

Fixing the Bug
#

We’ve been able to replicate the bug. 🥳 On the host machine, I’ll use the ot script which comes via Open::This to open the file locally at the appropriate line in my favourite editor.

ot t/open-this.t line 167

Then I’ll apply the following change:

diff --git a/t/open-this.t b/t/open-this.t
index a2e750e..f0b6220 100644
--- a/t/open-this.t
+++ b/t/open-this.t
@@ -168,7 +168,7 @@ local $ENV{EDITOR} = 'vim';
 parse_text($text),
 {
 file_name => 't/lib/Foo/Bar.pm',
- is_module_name => 1,
+ is_module_name => !!1,
 line_number => 3,
 original_text => $text,
 sub_name => 'do_something',

Now, when I run the tests again, they are passing. 🎉 Many thanks to SREZIC for once again helpfully pointing test failures out to me and ILMARI for showing me how to fix the test. 🙏

Read on website

posts on olafalders.com

Can Others Explain My Work Without Me?

Oops! I just broke git-bisect

Why This Matters #

The Common Anti-Pattern #

Making Review Easier, Not Harder #

On a Prettier PATH

The Default env #

The Sorted env #

The Split PATH #

A Tabular env #

A JSON env #

Logging env in CI via Markdown #

So Long! #

How Many Versions of "X" Are in my $PATH?

The Great PTS CLI Throwdown

Paul’s Picks #

Neovim plugins #

Shawn’s Picks #

ctrl-a #

tmux keybindings in WezTerm #

caps-lock ctrl + escape #

Mickey’s Picks #

ctrl-s stop streaming output #

cd is an alias to pushd #

zmv for mass renaming via regex #

Some favorite git commands #

git checkout -p #

git rebase -i #

git grep -W #

git push origin HEAD #

git branch –merged | grep -v master | xargs –no-run-if-empty git branch -d #

git clean -dfx #

Julien’s Picks #

peek #

Olaf’s Picks #

clipboard #

Battery Power-Ups: Enhancing SketchyBar with "is"

is: the new subcommands #

SketchyBar (Before) #

My Desktop #

My Laptop #

SketchyBar (After) #

Summary #

Debounce All of the Things

The TL;DR #

The Caveat #

The Setup #

The Problem #

Solution: Attempt the First #

Taking a Detour with Find #

Solution: Attempt the Second #

Creating a debounce Function in Bash #

Solution: Attempt the Third #

The Tips #

Running Multi-Step Commands #

Careful with Your Quotes #

The debounce in Your CI/CD Pipeline #

The debounce in Your Ansible #

The Conclusion #

How I Spent My First London Perl Workshop

Look Who’s Back #

Wheels Down London #

The Pre-Workshop Social #

The Workshop #

Thoughts on the Conference #

A Miniature meta::hack #

Hack Day, The Last #

I'm Still Lazy

This toy was somewhat broken #

Now it’s a better toy #

Have some fun with it #

At the command line #

In your code #

In a one-liner? #

How I Spent My Perl Toolchain Summit v2024 (Lisbon)

PTS 2024 in Lisbon #

Getting There #

Getting Settled #

Fado #

Why This Matters
#

The Common Anti-Pattern
#

Making Review Easier, Not Harder
#

The Default env
#

The Sorted env
#

The Split PATH
#

A Tabular env
#

A JSON env
#

Logging env in CI via Markdown
#

So Long!
#

Paul’s Picks
#

Neovim plugins
#

Shawn’s Picks
#

ctrl-a
#

tmux keybindings in WezTerm
#

caps-lock ctrl + escape
#

Mickey’s Picks
#

ctrl-s stop streaming output
#

cd is an alias to pushd
#

zmv for mass renaming via regex
#

Some favorite git commands
#

git checkout -p
#

git rebase -i
#

git grep -W
#

git push origin HEAD
#

git branch –merged | grep -v master | xargs –no-run-if-empty git branch -d
#

git clean -dfx
#

Julien’s Picks
#

peek
#

Olaf’s Picks
#

clipboard
#

is: the new subcommands
#

SketchyBar (Before)
#

My Desktop
#

My Laptop
#

SketchyBar (After)
#

Summary
#

The TL;DR
#

The Caveat
#

The Setup
#

The Problem
#

Solution: Attempt the First
#

Taking a Detour with Find
#

Solution: Attempt the Second
#

Creating a debounce Function in Bash
#

Solution: Attempt the Third
#

The Tips
#

Running Multi-Step Commands
#

Careful with Your Quotes
#

The debounce in Your CI/CD Pipeline
#

The debounce in Your Ansible
#

The Conclusion
#

Look Who’s Back
#

Wheels Down London
#

The Pre-Workshop Social
#

The Workshop
#

Thoughts on the Conference
#

A Miniature meta::hack
#

Hack Day, The Last
#

This toy was somewhat broken
#

Now it’s a better toy
#

Have some fun with it
#

At the command line
#

In your code
#

In a one-liner?
#

PTS 2024 in Lisbon
#

Getting There
#

Getting Settled
#

Fado
#

To Ride or not to Ride
#

Day 0
#

Day 1
#

Day 2
#

Day 3
#

The Sponsors
#

The Attendees
#

Welcome to Our Newest Sponsor
#

Cascais
#

Heading Home
#

That’s a Wrap
#