Lele's log, DEE Not-Enterprise, 2026

TIL that pathnames in git configs can be optional

Mon, 23 Feb 2026 00:00:00 GMT

git-blame shows what revision and author last modified each line of a file.

There are cases where you may want to ignore certain revisions, e.g. when a revision only contains changes that resulted from a code formatter changing the indentation of the entire codebase.

To ignore such commits, you can use:

git blame --ignore-rev <rev>

Or, you can ignore multiple revisions from a file:

git blame --ignore-revs-file <file>

By convention, the ignore-revs-file is called .git-blame-ignore-revs and placed at the repository root. Git forges like GitHub and GitLab support this file directly in their blame views.

If you want to default to .git-blame-ignore-revs for the ignore-revs-file locally, you can set the config option blame.ignorerevsfile... and figure out that it's a bad idea. git-blame fails if the ignore-revs-file doesn't exist - and in most repositories it doesn't exist. So don't set blame.ignorerevsfile.

... or so I thought until I read a comment by ilostmymangoman on hacker news. As of git 2.52 (Nov 2025), you can mark config file paths as optional using the :(optional) prefix.

That means you can safely configure an ignore-revs-file in your ~/.gitconfig without breaking git-blame if the file doesn't exist:

[blame]
    ignoreRevsFile = :(optional).git-blame-ignore-revs

First Impressions of Rust

Sun, 01 Feb 2026 00:00:00 GMT

Rust has been the "most admired" language in StackOverflow's surveys for 10 years straight¹. This sounds impressive. But the surveys don't tell you why. You can find plenty of opinions online, but as the curious mind I wish I were, I wanted to see for myself what makes people love Rust so much. So I started hacking on a little side project: git-forge, a CLI tool to interact with git forges using a unified interface. I wrote about it in my previous blog post. It was a nice way to dip my toes into Rust without getting overwhelmed by a giant existing codebase - especially since Rust is my first "systems programming language". In my day job, I'm a web developer with JavaScript, TypeScript, and a bit of Java as my main languages.

After writing Rust for a bit, I have to say that I like it - but not for the reasons people usually go to Rust for.

Rust's claim to fame is performance, efficiency, and memory safety without garbage collection. Frankly, I don't care for any of that. Not everyone operates at a scale where you need to squeeze out every last drop of performance, and I don't hit any limits with my current tech stack.

I like Rust because it's simply a pleasant language to use. Maybe I'll dislike it when I need to write my own macros, when I fight the borrow checker and worry about lifetimes more often, or when I deep-dive into concurrent and parallel programming... but it is not this day! This day we fight I like Rust. There are plenty of reasons for this. But let's go with the classic approach, and start with the bad and end with the good.

The Bad

The initial experience with Rust is nice. There are plenty of resources for beginners like the Rust Book or the Rustlings exercises. There is plenty of handholding and documentation. But eventually there's none of that. Eventually, you fight with the ownership system and the borrow checker... even though at first they sounded easy conceptually and looked manageable thanks to lifetime elision. Eventually, you look at other people's code and feel like you're studying an arcane magic book... even though you understand the syntax (in theory). Error messages are supposedly helpful... but only if someone (e.g. the Rust Book) points you to the exact sentence that matters. When you're on your own, you can feel lost in the noise.

I expect these struggles to ease with experience. What I'm less sure will improve is Rust's standard library. When I say "standard library", I don't mean std strictly; I mean what's officially supported by Rust. It feels tiny. I'd be completely fine with a small std if there were first-party opt-in crates maintained by the Rust team. Even for git-forge, which is relatively trivial, I needed to reach for a few libraries:

anyhow for convenient error handling
clap for argument parsing
reqwest for making HTTP requests
serde for (JSON) de/serialization

While I use other dependencies like ratatui, those four are the ones that hurt because they feel basic to me. My initial TypeScript implementation of git-forge had zero dependencies except for Node itself. It's obvious why Node includes tools for making HTTP requests and JSON de/serialization, but Node even includes simple argument parsing, which is great for things beyond basic shell scripts but short of full-blown "apps".

Reaching for dependencies always makes me a little uneasy. While I try to do some due diligence - checking who maintains a project, how many maintainers and contributors it has, how actively it's maintained - there's always a chance for something to go wrong. Just look at npm, which has seen multiple notable supply chain attacks recently². It's hard not to worry about the Jenga tower of dependencies behind many projects.

xkcd: dependency

It may be only a matter of time until we read about attacks on crates.io. Time will tell...

Those are my only real gripes with Rust at the moment. The list of things I enjoy is much longer.

The Good

I appreciate Rust's defaults, e.g. privacy and immutability. I like notUsingCamelCaseForReadabilityButInstead using_snake_case_which_is_more_readable_even_when_using_absurdly_long_names.

I like that Rust is expression-based. You don't need the ternary operator, just use if expressions (or other control flow). You don't need an IIFE (Immediately Invoked Function Expression) to create a new scope; just create a block that automatically evaluates to its last expression.

/* TypeScript */

// ternary operator
const status = isActive ? "active" : "inactive";

// IIFE for complex initialization
const config = (() => {
    const base = getBaseConfig();

    // ... more setup

    return {
        /* ... */
    };
})();

/* Rust */

// ternary -> normal if-else expression
let status = if is_active { "active" } else { "inactive" };

// IIFE -> just a block
let config = {
    let base = get_base_config();

    // ... more setup

    Config { /* ... */  } // block evaluates to this
};

Then there's pattern matching and exhaustive checks. They felt a bit foreign at first. They don't come as naturally in the languages I'm used to. But now I wouldn't want to go without them³.

/* Rust */

enum Status { Active, Inactive, Pending }

fn describe(status: Status) -> String {
    match status {
        Status::Active => String::from("active"),
        Status::Inactive => String::from("inactive"),
        // Compiler error: non-exhaustive pattern, `Pending` not covered.
    }
}

Rust's module system was another pleasant surprise. I always found it awkward in JavaScript/TypeScript that export means "public to the entire codebase". You need to rely on conventions (e.g. create an index.js file to declare a "soft" public API), keep all module code in a giant file, or break the code out into a separate library.

/* TypeScript */

// src/utils_module/internal_to_utils_module.ts
export function internal_util_function() {}

// This is allowed
// src/utils_module/another_util.ts
import { internal_util_function } from "./internal_to_utils_module.ts";

// But this is also allowed and can't be prevented :(
// src/some_module/index.ts
import { internal_util_function } from "../utils_module/internal_to_utils_module.ts";

Rust gives you more fine-grained control. It lets you cleanly separate modules within a project. Child modules automatically hide their implementation details from parent modules, while still being able to access parent code. So you can selectively (re)export things to create a proper public API. Here's the same example in Rust:

/* Rust */

// For simplicity, all modules are put into a single file, but you
// could split them out into separate files.

mod utils_module {
    mod internal_to_utils_module {
        pub fn internal_util_function() {}
    }

    mod another_util_module {
        fn some_func() {
            // internal_to_utils_module made internal_util_function pub
            // for the utils_module. So another_util_module can access it
            // as well since it can access everything in utils_module.
            super::internal_to_utils_module::internal_util_function();
        }
    }
}

mod some_module {
    // utils_module neither re-exported internal_util_function nor made
    // internal_to_utils_module public. That means, some_module can't
    // access internal_util_function :)
}

Rust's type system is another highlight. You can encode a lot of useful information to "make illegal states unrepresentable".

The Result type forces you to acknowledge possible failures instead of being surprised at runtime. I enjoy the idea so much that I tried to implement it in TypeScript (as have others). But it isn't as ergonomic as it is in Rust without pattern matching and the ? operator to propagate errors concisely.

The Option type explicitly represents the absence of a value. You can rely on a String being a String. Compare that to Java, where Optionals themselves can be null, and where you need to rely on third-party tools like NullAway to improve null safety.

The trait system initially looked like interfaces to me because they share the same goal: sharing behavior. But traits offer features that interfaces don't. My favorite is that you can implement your own traits for foreign types extending their implementation.

// Define your own trait
trait Slugify {
    fn slugify(&self) -> String;
}

// Implement it for String (from std)
impl Slugify for String {
    fn slugify(&self) -> String {
        self.to_lowercase().replace(' ', "-")
    }
}

// Now you can call it like a method
let title = String::from("My Blog Post");
let slug = title.slugify(); // "my-blog-post"

// In other languages, you'd write a standalone function like
// slugify(title) or modify String.prototype (in JS/TS), which pollutes
// the prototype

Rust's tooling is another plus. You get built-in linting, code formatting, documentation, package management, and testing. Compared to JS/TS/Java, where you need third-party tools. Rust also has features like documentation tests or inline (in-file) tests that I haven't commonly seen elsewhere. I especially like the inline tests. I can implement a function and verify it works without setting up a new test file or making the function public. Whether to keep those tests in the end is a different matter, but being able to test an implementation quickly and easily is great.

The End

Of course, none of these features are unique to Rust. Functional languages, strongly (and statically) typed languages, or insert-language-x offer many of them. I just haven't used any of those languages before; they always felt too different, too niche, or too something-else. Rust as a whole feels approachable and familiar enough. It strikes a nice balance between what it offers and its tradeoffs. If my future experience with Rust is as enjoyable as it has been so far, it might become my go-to language for new projects. I would recommend Rust - not because of its performance or safety (after all, I am unfit to speak about that) - but because Rust is simply a pleasant language to use.

Footnotes

See GitHub's Blog Post, which reviews the 2023 survey, SO survey 2024, and SO survey 2025 ↩
July 18, 2025, Nx in August 2025, Shai-Hulud in September 2025, Shai-Hulud 2.0 in November 2025 ↩
Well, technically, Java has some pattern matching and exhaustive switch expressions. TypeScript can use a never function to create an exhaustive switch or use lint rules. But these features aren't as powerful or ubiquitous as they are in Rust. ↩

git-forge: Faster Issues and PRs From Your Terminal

Tue, 09 Dec 2025 18:45:00 GMT

I often want to drop issue links into commit messages. Doing that normally means leaving your editor, opening a browser, navigating to the repo, finding the issue, and then copying the URL... a minor inconvenience, but one that happens often enough to be mildly annoying. I'm not the only one to feel this way. There are tools to address it. But they don't quite fit my needs: they either only work with one forge or don't offer the features I want. So I built git-forge.

git-forge is a small CLI that plugs into git via the git-<subcommand> pattern¹. Drop it somewhere in your $PATH and you can run:

git forge [<subcommand>] [<options>]

It works with GitHub, GitLab, Gitea, and Forgejo. If you only use GitHub, gh will give you signifcantly more features; but if you hop between forges, git-forge aims to be good enough. Here's a quick overview of what it can do.

Features

git forge issue fetches issues as TSV (Tab-separated values) so you can pipe them into whatever tools you already use. This makes it easy to search, filter, or copy links.

# In a repo for https://gitlab.gnome.org/GNOME/gnome-shell
$ git forge issue --per-page 5
8883 Brightness management is broken when there is more than one options in /sys/class/backlight	https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/8883
8881 Error sometimes when switching desktops using keyboard	https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/8881
8877 Occasional segfault at login, surrounded by object errors ("An object is already exported", "assertion 'G_IS_OBJECT (object)' failed")	https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/8877
8873 Passwords and keys desktop file not in Utilities folder because of wrong desktop file name	https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/8873
8870 Follow gtk-interface-reduced-motion	https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/8870

git forge pr has three actions.

git forge pr checkout <pr-number> checks out a pull request locally. I prefer reviewing code in my own dev environment, but I always forget the exact ref syntax for PRs.Is it pulls/<id>/head, pull/<id>/head, pull-requests/<id>/head? And what about GitLab, Forgejo, or Gitea? Now, I don't need to look it up anymore. git-forge streamlines this.

git forge pr list prints a list of pull requests as TSV, just like the issue command.

# In a repo of https://gitlab.gnome.org/GNOME/gnome-shell
$ git forge pr --per-page 5
3993 screenShield: Fix user deselection after idle in greeter	https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3993
3990 messageList: Preserve MPRIS art aspect ratio	https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3990
3984 layout: Simplify startup path if animations are disabled	https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3984
3980 unlockDialog: Tweak lock screen when limit reached	https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3980
3979 shellDBus: Add new BrightnessChanged signal to brightness interface	https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3979

git forge pr open opens a PR for the current branch. It's still somewhat experimental; I need to test it more (manually and automatically), especially on non-GitHub forges.

git forge web gives you quick access to URLs for the repo, issues page, or PR page.

# In a repo of https://gitlab.gnome.org/GNOME/gnome-shell
$ git forge web --type=repository
https://gitlab.gnome.org/GNOME/gnome-shell

Because git-forge is just a CLI, you can combine it with other commands. Some git aliases for inspiration:

# git aliases in .gitconfig
[alias]
    fcpissue = "!git forge issue | fzf | cut -f 2 | copy"
    fopenissue = "!git forge issue | fzf | cut -f 2 | xargs xdg-open &> /dev/null"
    freviewpr = "!git forge pr | fzf | cut -d' ' -f 1 | xargs git forge pr checkout"

For example, git fcpissue lets you fuzzy-search issues and then copies the URL to your clipboard so that you can add it to a commit message. git freviewpr lets you fuzzy-search PRs and checks the selected one out locally.

Quirks and Notes

git-forge tries to provide a common feature set across forges. But the forge APIs differ. For instance, GitHub's "issues" API returns both issues and PRs, so git-forge has to filter them client-side. That means requesting 100 items might give you fewer actual issues compared to GitLab, which separates them server-side. In practice, I think these quirks are minor.

git-forge is currently written in TypeScript. It doesn't rely on external dependencies (other than dev dependencies), but it does require Node to run. Node may be a turn-off for some people, but it's what I'm most confident in and it let me focus on the functionality first. I plan to rewrite git-forge in Rust. It's partly to learn and practice Rust, partly to drop the node runtime dependency. The rewrite can focus entirely on the technical implementation without changing the feature set.

[Edit] The Rust rewrite is complete. [/Edit]

If git-forge sounds interesting to you, you can find the project on GitHub.

Footnotes

https://git.github.io/htmldocs/howto/new-command.html ↩

Redesigning my Little Corner of the Web

Mon, 08 Dec 2025 18:00:00 GMT

I've recently redesigned my website. I went for a more terminal-y look. Here are some screenshots showing the old and new look.

Old Homepage

New Homepage

Layout-wise, my blog used to be very simple: just a list of all my posts in reverse chronological order. Yesterday, I read a blog post by Lalit Maganti about his own redesign, where he links to a post by Evan Martin. In that post, Martin argues that having a reverse-chronological homepage doesn't really make sense when your writing covers unrelated topics. And I do see his point, which is why I decided to rethink the layout of my blog as well.

Earlier this week, I had already added categories after reading Simon Willison's What to blog about. My categories are few and fixed in number. So they are a natural way to structure the landing page.

So now, the page shows the three most recent posts in each category.

Old Blog

New Blog

I tried a multi-column layout, but because the category descriptions and post cards vary in length, posts and text were misaligned. I didn't like that, so I went with a single-column design instead. Since the landing page no longer lists all posts, I also added an archive, which is basically the old view: a full reverse-chronological list.

And lastly, loosly inspired by Simon Willison's Link Blog and Blogrolls, I added a section in the sidebar with links to posts I've enjoyed reading. I'm calling it "Across the Blog-verse" (a reference to Across the Spider-Verse). It's a manually curated list, and I'll update it whenever I come across something great. Check it out here.

Reaching for the Stars with Astro

Sat, 01 Mar 2025 22:00:00 GMT

Flashy ⭐⭐⭐ nonsense title aside, I've switched from Jekyll to Astro as my static site generator and wanted to share my reasons behind the switch and my experience with it.

Background

Previously, my website consisted of only a blog built with Jekyll using the chirpy theme without any customization from my end. The theme looks great but now I wanted to add a bit of a personal touch, create a homepage, and customize the styling.

Demo of chirpy theme

Jekyll is written in Ruby. I don't know Ruby or its ecosystem. While everything I wanted to do right now would be feasible in Jekyll, I wanted to switch to a tool that I can more easily work with, i.e., one that is JavaScript/TypeScript-based. Plus, having a fun small side project certainly was another motivating factor 🙃. So, I went and looked around to see what static site generators (SSG) exist. My requirements were that it is simple and lightweight (no JS by default), not be tied to a specific frontend framework, and little to zero-config. After a bit of research, I narrowed down my choice to Astro and Eleventy. While I went with Astro, Eleventy definitely has some benefits over it.

Eleventy has noticeably faster build times (according to Eleventy themselves). They take 1.93 seconds to build 4.000 markdown files, while Astro needs 22.9 seconds. That's definitely impressive, but not something that matters for my personal website. I doubt I will ever come close to a number of files that would increase the build time to more than a few seconds.

Additionally, Eleventy's philosophy appears more personal and friendly, while Astro feels more professional and corporate. For instance, Eleventy doesn't collect telemetry, while Astro does... but they do ask if you want to opt-out.

But the deciding factor in favor of Astro was the documentation. Astro has a simple hands-on tutorial to build a blog on their website. It contains everything you need from A-Z. It's a killer feature. Their sidebar is also structured very well. Eleventy, on the other hand, has a huge sidebar. It contains like 3 times the items of Astro's sidebar. It's overwhelming. Also, their tutorials link to YouTube videos (partially by third parties and partially quite old) or GitHub repos. Both don't feel as well integrated or beginner-friendly as Astro's official on-site, step-by-step tutorial.

That said, one thing I do want to highlight about Eleventy's documentation is that they feature it very prominently on their homepage. It is hard to miss... and it even sticks to the top of the screen when you scroll 😂

Elventy's documentation button

The Experience of Using Astro for the First Time

The developer experience of Astro is amazing. They have a great tutorial which only takes about 30 minutes or so and teaches you everything you need to build static sites. If you know HTML, CSS, and JS, you can jump straight into it and you will breeze right through because Astro is very straightforward to use. Their component/templating language is JSX-like, which is nice. After all, JSX is basically just HTML + JS. The only difference I've noticed is that you don't use camelCase but kebab-case, making this even more similar to HTML.

Styling is just CSS, which is scoped by default (nice!). Options for libraries like Tailwind and preprocessors are available when needed.

I didn't need to edit my markdown files to accommodate Astro. In fact, I could even remove {% raw %} and {% endraw %} which came from Jekyll/Liquid. Customizing the markdown-to-HTML build process is possible with plugins, which you can write yourself. I've used plugins to add a copy button to code sections and to auto-link headings.

Providing an RSS feed for my blog was easy as there is an official package and guide. Deploying to GitHub Pages is just as simple since Astro provides a workflow template and maintains an official GitHub Action.

Now let's talk about issues I ran into when using Astro... there were none, which, I guess, isn't surprising. After all, I only used Astro to generate a homepage and a blog, which are the most basic things you can do with a SSG. So I wouldn't expect anyone to run into any issues when using any SSG for that use case. The only challenge was, that I needed to style everything myself, which is the price you pay when you don't use a theme and want to have full control.

[Edit] Well, just after publishing this post. I've noticed an issue. There is a difference between the dev environment and the production code that runs. The images in the production were broken because I've used absolute paths when referencing them. In the dev environment that worked... 😅 [/Edit]

Future Plans

My site itself is still a work-in-progress, e.g., I am missing a light mode; there are possible accessibility concerns since I used some input element hacks to stick to HTML-and-CSS-only as much as possible; and my project showcase isn't done yet.

As for my usage of Astro, I am pretty happy with that except that I still need to handle videos and images better. Another thing on my TODO list is to explore the content collections API because that seems to be the perfect fit for a blog. Let me quote Astro for the benefits of using content collections here

Collections help to organize and query your documents, enable Intellisense and type checking in your editor, and provide automatic TypeScript type-safety for all of your content.

However, all those things are for future-me. My site works well enough at the moment.

Hindsight: 20/20

Overall, my switch to Astro went great thanks its simplicity and documentation. I would recommend Astro, it's a 20/20 for me. If you know HTML, CSS, and JS, you need to learn very little to use it. Now I have full control over the look and feel of my website - with all the pros and cons that come with said control.

Keyboard shortcut sequences in GNOME extensions

Sun, 25 Aug 2024 23:00:00 GMT

I've been prototyping what I call keyboard shortcut sequences in a GNOME extension. I grew fond of them while using certain apps and wanted to document my results here.

Motivation

In modern operating systems and most apps, keyboard shortcuts only consist of a single combination of possibly multiple modifier keys and one non-modifier key. Modifiers are keys like Ctrl or Shift and non-modifier keys are, well, the remaining keys. An example of this type of keyboard shortcut is Ctrl C.

Keyboard shortcuts are easier to remember if the keys can serve as a mnemonic or if there is some kind of system to them. For instance, Ctrl C to copy, Ctrl S to save, Ctrl F to find, Ctrl P to print, and so on. But there are only so many permutations of different modifier keys and a single non-modifier key. Eventually, you'll end up with shortcuts that appear arbitrary and unsystematic, making them harder to remember.

This is where keyboard shortcut sequences come in. Shortcuts aren't triggered by a single key combination, but by a sequence of key combinations. This way, you can create a (hierarchical) system for shortcuts. Let's take Ctrl Del ➝ w as an example for a shortcut sequence. This shortcut would be triggered like this

Hold Ctrl and then press Backspace
Release Ctrl and Backspace
Press w

An action for this shortcut could be to delete the next word in an text editor; Ctrl Del ➝ l could delete the next line; and Ctrl Del ➝ p could delete an entire paragraph. This looks easy to remember, right? You basically only need to remember 1 key combination (Ctrl Backspace). It's certainly easier than remembering 3 random looking shortcuts.

The idea is not mine. There are apps that implement shortcut sequences like emacs and its key sequences, VSCode's chords (which is a bit of misnomer), zed, vim, and logseq to name a few. The advantage is that every shortcut can be semantically meaningful because the amount of possible combinations is infinite. Of course, an absurdly long sequence is problematic as well. The fundamental idea is to create keyboard shortcuts that are easy to remember.

Prototyping shortcut sequences in a GNOME extension

GNOME does not natively support shortcut sequences. A shortcut consists of modifier keys and one non-modifier key. Although shortcuts are saved as a string array, the items in the array only serve as alternative triggers for the same action. For example, in GNOME 47 Super Alt Right and Super PageDown both switch to the workspace to the right. I am not a linux desktop developer. So I don't know what would need to happen or which parties would need to be involved to develop this feature properly. Since I am developing GNOME extensions, I wanted to explore the possibility of including shortcut sequences, even if it's a hacky implementation. At least it could be a feature that is here now. So I've created a prototype which does just that. And it works... mostly. I'll go through some limitations later. But for now, let's look at the implementation. Let's start with a high-level overview of the implementation.

Since shortcuts can only consist of 1 key combination in GNOME, it makes sense to split shortcut sequences into 2 parts. The first part - let's call it prefix - will be registered as a normal shortcut with GNOME. When a prefix is activated, the GNOME extension creates a widget that grabs the keyboard input, listens to the subsequent keys, and filters for matching shortcut sequences.

Let's go into more detail. In the settings schema XML file, I define keyboard shortcuts as usual but also add additional hidden keys for the prefixes.

<!-- The following entries are shortcut sequences. This shortcut will be     -->
<!-- registered with GNOME shortcut systemThe first item in the array is the -->
<!-- prefix. The subsequent items are the key symbols and modifiers          -->
<!-- separated by `+` for  each key combinination in a shortcut sequence.    -->
<!-- The reasoning behind it follows below the code snippet.                -->

<key name="focus-left" type="as">
    <default>['&lt;Super&gt;f','97+0']</default>
</key>
<key name="focus-right" type="as">
    <default>['&lt;Super&gt;f','98+0']</default>
</key>

<!-- This is a non-sequenced aka 'normal' shortcut because it's an array of  -->
<!-- length 1. This shortcut will be registered with GNOME's shortcut system -->

<key name="focus-right" type="as">
    <default>['&lt;Super&gt;g']</default>
</key>

<!-- additional keys for the prefixes of shortcut sequences -->

<key name="multi-stage-shortcut-activator-0" type="as">
    <default>['&lt;Super&gt;f']</default>
</key>
<key name="multi-stage-shortcut-activator-1" type="as">
    <default>[]</default>
</key>
<key name="multi-stage-shortcut-activator-2" type="as">
    <default>[]</default>
</key>

Then I have a shortcuts.js file that actually implements the logic on GNOME Shell's side. The entry for the logic is Shortcuts::register. You'll notice that shortcut sequences aren't registered with GNOME's native keybinding system because, as mentioned, GNOME doesn't support the concept of shortcut sequences. So instead of registering the shortcut sequences, I only register the prefixes and create a custom handler, the MultiStageShortcutManager, for the prefixes. Note that I used the term activator instead of prefix in the code. Another thing worth explaining is, starting with the second item, shortcut sequences save the key combinations as key symbols + a modifier state to compare them against the event in MultiStageShortcutManager::vfunc_key_press_event since I couldn't find a way to transform the Clutter event into the equivalent accelerator label.

// shortcuts.js

import {
    Clutter,
    GLib,
    GObject,
    Main,
    Meta,
    Shell,
    St,
} from "./dependencies.js";

import { updateMultiStageShortcutActivators } from "../shared.js";
import { Settings } from "./settings.js";
import { Timeouts } from "./timeouts.js";

/** @type {Shortcuts} */
let SINGLETON = null;

function enable() {
    SINGLETON = new Shortcuts();
}

function disable() {
    SINGLETON.destroy();
    SINGLETON = null;
}

const INVALID_KEY_SEQUENCE_STATUS_LABEL = "Invalid shortcut...";
const NO_INPUT_STATUS_LABEL = "No input given...";
const WAITING_FOR_NEXT_KEY_STATUS_LABEL = "Waiting for next keys...";
const UNKNOWN_ERROR_STATUS_LABEL = "Unknown error...";

class Shortcuts {
    /** @type {string[]} */
    _registeredShortcuts = [];

    /** @type {MultiStageShortcutManager} */
    _multiStageShortcutManager = new MultiStageShortcutManager();

    constructor() {
        // This keeps the prefixes in sync with the shortcut sequences at least
        // on `enable` in case the user changed the shortcuts from the outside
        updateMultiStageShortcutActivators(Settings.getGioObject());
    }

    destroy() {
        Settings.unwatch(this);

        this._registeredShortcuts.forEach((shortcut) =>
            Main.wm.removeKeybinding(shortcut),
        );
        this._registeredShortcuts = [];

        this._multiStageShortcutManager.destroy();
        this._multiStageShortcutManager = null;
    }

    /**
     * @param {object} param
     * @param {ShortcutKey} param.key
     * @param {Function} [param.handler] - optional only for sequence prefixes
     * @param {Meta.KeyBindingFlags} [param.flags]
     * @param {Shell.ActionMode} [param.modes]
     */
    register({
        key,
        handler = () => {},
        flags = Meta.KeyBindingFlags.IGNORE_AUTOREPEAT,
        modes = Shell.ActionMode.NORMAL,
    }) {
        if (this._registeredShortcuts.includes(key)) {
            throw new Error(`Shortcut "${key}" is already registered.`);
        }

        this._watchShortcutTypeChange(key, handler, flags, modes);

        if (this._isMultiStageShortcut(key)) {
            this._multiStageShortcutManager.register(key, handler);

            return;
        }

        let shortcutAddedSuccessfully = false;

        if (this._isMultiStageShortcutPrimaryActivator(key)) {
            shortcutAddedSuccessfully = Main.wm.addKeybinding(
                key,
                Settings.getGioObject(),
                flags,
                modes,
                () => this._multiStageShortcutManager.start(key),
            );
        } else {
            shortcutAddedSuccessfully = Main.wm.addKeybinding(
                key,
                Settings.getGioObject(),
                flags,
                modes,
                handler,
            );
        }

        if (shortcutAddedSuccessfully) {
            this._registeredShortcuts.push(key);
        }
    }

    _isMultiStageShortcut(key) {
        return (
            Settings.getGioObject().get_strv(key).length > 1 &&
            !this._isMultiStageShortcutPrimaryActivator(key)
        );
    }

    _isMultiStageShortcutPrimaryActivator(key) {
        return key.match(/^multi-stage-shortcut-activator-\d+$/);
    }

    /**
     * @param {string} key
     * @param {Function} handler
     * @param {Meta.KeyBindingFlags} flags
     * @param {Shell.ActionMode} modes
     */
    _watchShortcutTypeChange(key, handler, flags, modes) {
        if (this._isMultiStageShortcutPrimaryActivator(key)) {
            return;
        }

        const id = Settings.watch(
            key,
            () => {
                // Multi-Stage -> Multi-Stage and Single -> Single shortcut
                // changes don't need to be handled. The reason for Multi-Stage
                // -> Multi-Stage is that we dynamically fetch the secondary
                // activators from the settings while the primary activator
                // (multi-stage-shortcut-activator-X) is registered just like a
                // Single shortcut and thus managed by the native keybinding
                // system. The later part applies to the Single -> Single
                // shortcut changes as well.

                const multiStageToSingle =
                    this._multiStageShortcutManager.isRegistered(key) &&
                    !this._isMultiStageShortcut(key);
                const singleToMultiStage =
                    !this._multiStageShortcutManager.isRegistered(key) &&
                    this._isMultiStageShortcut(key);

                if (multiStageToSingle) {
                    Settings.unwatch(id);

                    this._multiStageShortcutManager.unregister(key);

                    this.register({ key, handler, flags, modes });
                } else if (singleToMultiStage) {
                    Settings.unwatch(id);

                    Main.wm.removeKeybinding(key);
                    this._registeredShortcuts =
                        this._registeredShortcuts.filter(
                            (shortcut) => shortcut !== key,
                        );

                    this.register({ key, handler, flags, modes });
                }
            },
            { tracker: this },
        );
    }
}

class MultiStageShortcutManager extends Clutter.Actor {
    static {
        GObject.registerClass(this);
    }

    /** @type {Clutter.GrabState|null} */
    _grab = null;

    /** @type {Map<string, Function}>} */
    _handlers = new Map();

    /** @type {{primaryActivator: string, secondaryActivators: string[], handler: Function}[]} */
    _matchingMultiStageShortcuts = [];

    _statusLabel = new St.Label({
        opacity: 127,
        y_align: Clutter.ActorAlign.CENTER,
        visible: false,
    });

    constructor() {
        super({ reactive: true, visible: false });

        Main.panel._leftBox.add_child(this._statusLabel);
        global.stage.add_child(this);
    }

    destroy() {
        this._finish();

        this._handlers = null;
        this._matchingMultiStageShortcuts = null;

        this._statusLabel.destroy();
        this._statusLabel = null;

        super.destroy();
    }

    start(shortcutKey) {
        this.show();

        this._grab = Main.pushModal(this);

        if ((this._grab.get_seat_state() & Clutter.GrabState.KEYBOARD) === 0) {
            this._finish(UNKNOWN_ERROR_STATUS_LABEL);

            return;
        }

        if (this._statusLabelHideTimer) {
            Timeouts.remove(this._statusLabelHideTimer);
            this._statusLabelHideTimer = 0;
        }

        this._statusLabel.show();
        this._statusLabel.text = WAITING_FOR_NEXT_KEY_STATUS_LABEL;

        this._matchingMultiStageShortcuts = [];

        const [activator] = Settings.getGioObject().get_strv(shortcutKey);

        this._handlers.forEach((handler, scKey) => {
            const [shortcutActivator, ...secondaryActivators] =
                Settings.getGioObject().get_strv(scKey);

            if (shortcutActivator === activator) {
                this._matchingMultiStageShortcuts.push({
                    handler,
                    primaryActivator: shortcutActivator,
                    secondaryActivators,
                });
            }
        });

        this._startWaitingForInputTimer();
    }

    register(shortcut, handler) {
        return this._handlers.set(shortcut, handler);
    }

    unregister(shortcut) {
        return this._handlers.delete(shortcut);
    }

    isRegistered(shortcut) {
        return this._handlers.has(shortcut);
    }

    vfunc_key_press_event(event) {
        this._startWaitingForInputTimer();

        const eventKeyval = event.get_key_symbol();

        if (this._ignoreKeyval(eventKeyval)) {
            return Clutter.EVENT_STOP;
        }

        for (
            let i = this._matchingMultiStageShortcuts.length - 1;
            i >= 0;
            i--
        ) {
            const matchingMultiStageShortcut =
                this._matchingMultiStageShortcuts[i];
            const { secondaryActivators } = matchingMultiStageShortcut;
            const nextActivator = secondaryActivators.shift();
            const [nextKeyval, nextModifiers] = nextActivator.split("+");
            const isMatchingActivator =
                nextKeyval === String(eventKeyval) &&
                // Wayland includes NumLock/fn as part of the state.
                (nextModifiers ?? "0") ===
                    String(event.get_state() & ~Clutter.ModifierType.MOD2_MASK);

            if (isMatchingActivator) {
                if (secondaryActivators.length === 0) {
                    this._finish();
                    matchingMultiStageShortcut.handler();

                    return Clutter.EVENT_STOP;
                }
            } else {
                this._matchingMultiStageShortcuts.splice(i, 1);
            }
        }

        if (this._matchingMultiStageShortcuts.length === 0) {
            this._finish(INVALID_KEY_SEQUENCE_STATUS_LABEL);
        }

        return Clutter.EVENT_STOP;
    }

    _finish(error = "") {
        if (this._grab) {
            Main.popModal(this._grab);
            this._grab = null;
        }

        this._matchingMultiStageShortcuts = [];

        if (this._waitingForInputTimer) {
            Timeouts.remove(this._waitingForInputTimer);
            this._waitingForInputTimer = 0;
        }

        if (error) {
            this._statusLabel.show();
            this._statusLabel.text = error;
            this._statusLabelHideTimer = Timeouts.add({
                interval: 1500,
                fn: () => {
                    this._statusLabelHideTimer = 0;
                    this._statusLabel.hide();

                    return GLib.SOURCE_REMOVE;
                },
            });
        } else {
            this._statusLabel.hide();
        }

        this.hide();
    }

    _ignoreKeyval(keyval) {
        return [
            Clutter.KEY_Alt_L,
            Clutter.KEY_Alt_R,
            Clutter.KEY_Control_L,
            Clutter.KEY_Control_R,
            Clutter.KEY_Meta_L,
            Clutter.KEY_Meta_R,
            Clutter.KEY_Shift_L,
            Clutter.KEY_Shift_Lock,
            Clutter.KEY_Shift_R,
            Clutter.KEY_Super_L,
            Clutter.KEY_Super_R,
        ].includes(keyval);
    }

    _startWaitingForInputTimer() {
        this._waitingForInputTimer = Timeouts.add({
            name: "shell/shortcuts.js/MultiStageShortcutManager/_startWaitingForInputTimer",
            interval: 3000,
            fn: () => {
                this._waitingForInputTimer = 0;
                this._finish(NO_INPUT_STATUS_LABEL);

                return GLib.SOURCE_REMOVE;
            },
        });
    }
}

export { disable, enable, SINGLETON as Shortcuts };

There is also some code on the prefs.js side that handles the UI, sets the gsettings if the user changed the shortcuts, and keeps the gsettings for the prefixes in sync with the gsettings for the shortcut sequences. However, that is a bit too much to share here and fairly straightforward.

And that's it. It wasn't really hard to implement. That said, the current implementation has some issues, which I am not sure are fixable. But they aren't that big of a deal.

Limitations

The main issues are

Super <NON_MODIFIER_KEY> as a non-prefix key combination doesn't register on the initial press. For example, if the shortcut sequence is Super a ➝ Super a, and you press Super a, let go of a and the Super key, and press Super a again, it won't work. You need to keep holding Super after activating the prefix or press Super a twice after activating the prefix. I believe this is related to Super being used for the overview and not reaching MutliStageShortcutManager::vfunc_key_press_event on the first press. If I set the overview key to the right Super key, it works fine with the left Super key.
Some popups might close when the widget initiates the grab.

Less important issues are

When opening the shortcut editor in the preference window, I clear all prefix shortcuts so that the shortcut editor can capture the keyboard events, otherwise a keyboard shortcut sequence will be triggered if a prefix is activated. When the shortcut editor closes I re-set the prefixes. This is, at least in theory, problematic if the preference window crashes or is killed, as the prefixes won't be re-enabled. But that should be a rare case and the prefixes will be re-enabled the next time the preference window is opened or the extension is re-enabled.
And lastly, since a keyboard shortcut sequence consists of 2 gsettings, things may break if a user manipulates the gsettings directly via CLI or dconf editor instead of going through the preference window where I do the state syncing. I don't expect this to be big issue though since it's not a common thing to do.

There might be more issues, but I haven't found them yet. I will update this post if I do.

Conclusion

Keyboard shortcuts are easier to remember if the keys serve as a mnemonic or if there is a systematic structure to them.

Traditional shortcuts, triggered by a single combination of at least one modifier key and one non-modifier key, can be hard to remember because there are only a limited number of possible combinations. So if you have many shortcuts, the keys for a shortcut will end up looking random with no relation to the action they will trigger.

Keyboard shortcut sequences solve this problem. Shortutcut sequences are triggered by a sequence of key combinations rather than just one combination. This increases the amount of possible key combinations for one shortcut to practically infinity. That way the keys for a shortcut can always serve as a mnemonic for the action they perform. Some apps already offer these types of shortcut. Hopefully, in the future more apps or even operating systems support them natively. For now, I experimented with them in a GNOME extension, albeit in a pretty hacky manner.

Creating my first npm Package

Mon, 22 Jul 2024 20:00:00 GMT

Recently at work, I've started doing a bit of web development. What surprised me the most, in a pleasant way, was how nice the developer experience was. Everything is fairly straightforward to use, well-documented, and there are a lot of tools available. For instance, Vue and React provide scaffolding tools (create-vue and create-react-app, respectively) that set up your project quickly so you can hit the ground running. I thought to myself Oh, that's nice, let's steal be inspired by the idea and created something similar for my own use case. Enter create-gnome-extension, my first npm package.

What is create-gnome-extension?

Let's first define what GNOME extensions are. GNOME extensions are community written code that modify GNOME Shell, the graphical interface for the GNOME desktop.

Currently, getting started with developing GNOME extensions can be a bit cumbersome. You either manually create the project structure from scratch or use GNOME Shell's built-in

gnome-extensions create

command. However, this command doesn't offer much convenience as it places the files in ~/.local/share/gnome-shell/extensions/, which is the install directory for user extensions, and only creates the mandatory files. Developer tools or other conveniences are not included.

create-gnome-extension - similar to other create-X packages - follows a batteries included philosophy. Here's a short rundown in case you don't know how packages like this work. If you run:

npm create gnome-extension@latest # Note the space after `create`

npm will look up the latest create-gnome-extension package, temporarily install it, and execute the main bin defined in the package.json¹. So, create-gnome-extension is basically just a glorified Node script. When you use it, it will prompt some questions like Do you want to use TypeScript? and create the project structure for you. Check out the README for more information.

Developing create-gnome-extension

Now, I'd like to talk about how it was developing the npm package because there are some things to say. Developing create-gnome-extension itself was pretty straightforward. It's just a simple script that copies and writes some files.

However, I did have a bit of trouble with testing and publishing the package. It was not a great experience.

The only ways I found to actually test a package are to either publish it on npm or use npm link. Both aren't particularly great options. The first option is obviously not ideal, and the second option is just kind of slow. If you know of a better way to test a package, please let me know.

Another issue I encountered is about how files are included in an npm package. Some files, like the README or LICENSE, are always included, while most files need to be manually included. Other files are always excluded with no way to force-include them (like .gitignore)². You need to work around it by renaming those files. There is npm pack --dry-run that will tell you which files will be included in the package but manually checking that dozens or hundreds of files are actually part of the packge doesn't seem like a good developer experience. In the end, you have to read the documentation on the file patterns carefully to see how each file may be handled to avoid surprises.

New Project, new Ideas

Since create-gnome-extension was a new project, it gave me a chance to try out some new things.

I switched from ESLint and Prettier to Biome. Biome combines a formatter and linter, so there is one less dependency and fewer config files. It is also faster since it is written in Rust rather than JavaScript. However, the speed advantage is less significant since you likely use linters and formatters integrated into your code editor. That's where I had issues with Biome. The VSCode extension seems less reliable (as in it stops working sometimes). So, I will probably switch back to ESLint and Prettier once I start working on create-gnome-extension again.

I also started using conventional-changelog and conventional-recommended-bump, which are based on the Angular commit convention, to automatically bump the version number and generate the CHANGELOG. This works quite well so far. Although, I am unsure about what happens if one type of work needs to be split into multiple commits, e.g., one feature implemented via multiple commits. I believe, if you prefix all commits of a merge request with feat, each commit would appear in the changelog, which is undesirable.

Related to the usage of conventional-X: I experimented with git hooks to ensure that commit messages follow the Angular convention or at least warn if the convention is obviously not adhered to. The idea was to avoid the need to push to a merge request and wait for feedback from the CI. The problem with git hooks is that they are only local to repos and won't be included when pushed to remotes. So, I put the hooks in a .githooks directory and added a postinstall npm script that runs

git config --local core.hooksPath .githooks

so that the hooks are automatically set up when you work on the project. However, this led to an error when running npm create gnome-extension@latest since the package wouldn't be initialized as a git repo. So, I turned the postinstall script into an optional hookup script for now. Maybe using husky would solve this issue but I didn't want to add a dependency just for that.

Finally, I also created some GitHub actions. The most interesting action appends the URL of the merge request (MR) to all commits before initiating a merge. This allows you to easily open the MR from a terminal on your local machine to look at the discussion that surrounded an MR. This is inspired by the Part-of trailer of marge-bot for GitLab.

Final Thoughts

While there are still some features to implement in create-gnome-extension, working on it so far was a fun little project. It allowed me to explore new tools and experiment with some other things.

Footnotes

npm create is an alias for npm init. So checkout the documentation for it here: https://docs.npmjs.com/cli/v6/commands/npm-init?v=true#description ↩
https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#files ↩