herbstluftwm: Make herbstclient alias optional

The `herbstclient` alias in the generated `autostart` made it impossible
to use bash functions.

This makes the `herbstclient` alias optional by adding an extra
`herbstclientAlias` option on the herbstluftwm configuration. The new
option defaults to `false` as to not confuse newcomers to the
herbstluftwm module, which is not a breaking change because it was only
an optimization.

modules/misc/news/2025/12/2025-12-12_19-20-28.nix

@@ -0,0 +1,12 @@
+{ config, ... }:
+
+{
+  time = "2025-12-12T19:20:28+00:00";
+  condition = config.xsession.windowManager.herbstluftwm.enable;
+  message = ''
+    It is now possible to disable the `herbstclient` alias in the autostart
+    script by setting `xsession.windowManagers.herbsluftwm.enableAlias = false`.
+    This makes it possible to use the `herbstclient` command in bash functions,
+    though may cause flickering while the autostart script runs.
+  '';
+}

modules/services/window-managers/herbstluftwm.nix

@@ -119,6 +119,24 @@ in
         {file}`$XDG_CONFIG_HOME/herbstluftwm/autostart`.
       '';
     };
+
+    enableAlias = lib.mkOption {
+      type = lib.types.bool;
+      default = true;
+      description = ''
+        Set an alias for the {command}`herbstclient` command in the
+        {file}`autostart` script that only stores its arguments and executes
+        them all at once at the end of the {file}`autostart` script.
+
+        This reduces the amount of flickering you get while all options are
+        being applied and improves the performance.
+
+        On the other hand, this makes it more difficult to write bash functions
+        that call {command}`herbstclient`. You can work around this by calling
+        {command}`command herbstclient` in your functions to still get some of
+        the benefits of enabling this alias.
+      '';
+    };
   };
 
   config = lib.mkIf cfg.enable {
@@ -131,11 +149,13 @@ in
     xsession.windowManager.command = "${cfg.package}/bin/herbstluftwm --locked";
 
     xdg.configFile."herbstluftwm/autostart".source = pkgs.writeShellScript "herbstluftwm-autostart" ''
-      shopt -s expand_aliases
+      ${lib.optionalString cfg.enableAlias ''
+        shopt -s expand_aliases
 
-      # shellcheck disable=SC2142
+        # shellcheck disable=SC2142
-      alias herbstclient='set -- "$@" ";"'
+        alias herbstclient='set -- "$@" ";"'
-      set --
+        set --
+      ''}
 
       herbstclient emit_hook reload
 
@@ -169,7 +189,9 @@ in
 
       herbstclient unlock
 
-      ${cfg.package}/bin/herbstclient chain ";" "$@"
+      ${lib.optionalString cfg.enableAlias ''
+        ${cfg.package}/bin/herbstclient chain ";" "$@"
+      ''}
     '';
   };
 }

tests/modules/services/herbstluftwm/default.nix

@@ -3,4 +3,5 @@
 lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
   herbstluftwm-simple-config = ./herbstluftwm-simple-config.nix;
   herbstluftwm-no-tags = ./herbstluftwm-no-tags.nix;
+  herbstluftwm-alias-disabled = ./herbstluftwm-alias-disabled.nix;
 }

tests/modules/services/herbstluftwm/herbstluftwm-alias-disabled-autostart

@@ -0,0 +1,47 @@
+#!/nix/store/00000000000000000000000000000000-bash/bin/bash
+
+
+herbstclient emit_hook reload
+
+# Reset everything.
+herbstclient attr theme.tiling.reset 1
+herbstclient attr theme.floating.reset 1
+herbstclient keyunbind --all
+herbstclient mouseunbind --all
+herbstclient unrule --all
+
+herbstclient set always_show_frame true
+herbstclient set default_frame_layout max
+herbstclient set frame_bg_active_color '#000000'
+herbstclient set frame_gap 12
+herbstclient set frame_padding -12
+
+for tag in 1 'with space' 'wə1rd#ch@rs'\'''; do
+  herbstclient add "$tag"
+done
+
+if @herbstluftwm@/bin/herbstclient object_tree tags.by-name.default &>/dev/null; then
+  herbstclient use 1
+  herbstclient merge_tag default 1
+fi
+
+
+herbstclient keybind Mod4-1 use 1
+herbstclient keybind Mod4-2 use 2
+herbstclient keybind Mod4-Alt-Tab cycle -1
+herbstclient keybind Mod4-Tab cycle 1
+
+herbstclient mousebind Mod4-B1 move
+herbstclient mousebind Mod4-B3 resize
+
+herbstclient rule focus=on
+herbstclient rule windowtype~'_NET_WM_WINDOW_TYPE_(DIALOG|UTILITY|SPLASH)' focus=on pseudotile=on
+herbstclient rule class~'[Pp]inentry' instance=pinentry focus=on floating=on floatplacement=center keys_inactive='.*'
+
+herbstclient use 1
+
+
+herbstclient unlock
+
+
+

tests/modules/services/herbstluftwm/herbstluftwm-alias-disabled.nix

@@ -0,0 +1,49 @@
+{ lib, pkgs, ... }:
+
+{
+  xsession.windowManager.herbstluftwm = {
+    enable = true;
+    settings = {
+      always_show_frame = true;
+      default_frame_layout = "max";
+      frame_bg_active_color = "#000000";
+      frame_gap = 12;
+      frame_padding = -12;
+    };
+    keybinds = {
+      "Mod4-1" = "use 1";
+      "Mod4-2" = "use 2";
+      "Mod4-Tab" = "cycle 1";
+      "Mod4-Alt-Tab" = "cycle -1";
+    };
+    mousebinds = {
+      "Mod4-B1" = "move";
+      "Mod4-B3" = "resize";
+    };
+    rules = [
+      "focus=on"
+      "windowtype~'_NET_WM_WINDOW_TYPE_(DIALOG|UTILITY|SPLASH)' focus=on pseudotile=on"
+      "class~'[Pp]inentry' instance=pinentry focus=on floating=on floatplacement=center keys_inactive='.*'"
+    ];
+    tags = [
+      "1"
+      "with space"
+      "wə1rd#ch@rs'"
+    ];
+    extraConfig = ''
+      herbstclient use 1
+    '';
+    enableAlias = false;
+  };
+
+  test.stubs.herbstluftwm = { };
+
+  nmt.script = ''
+    autostart=home-files/.config/herbstluftwm/autostart
+    assertFileExists "$autostart"
+    assertFileIsExecutable "$autostart"
+
+    normalizedAutostart=$(normalizeStorePaths "$autostart")
+    assertFileContent "$normalizedAutostart" ${./herbstluftwm-alias-disabled-autostart}
+  '';
+}

tests/modules/services/herbstluftwm/herbstluftwm-no-tags-autostart

@@ -5,6 +5,7 @@ shopt -s expand_aliases
 alias herbstclient='set -- "$@" ";"'
 set --
 
+
 herbstclient emit_hook reload
 
 # Reset everything.
@@ -30,3 +31,4 @@ herbstclient unlock
 
 @herbstluftwm@/bin/herbstclient chain ";" "$@"
 
+

tests/modules/services/herbstluftwm/herbstluftwm-simple-config-autostart

@@ -5,6 +5,7 @@ shopt -s expand_aliases
 alias herbstclient='set -- "$@" ";"'
 set --
 
+
 herbstclient emit_hook reload
 
 # Reset everything.
@@ -49,3 +50,4 @@ herbstclient unlock
 
 @herbstluftwm@/bin/herbstclient chain ";" "$@"
 
+