Skip to content

Tell GRUB Macs to run mkinitcpio -P after changing the keyboard's fnmode - #111

Merged
scottjones merged 1 commit into
omacom:mainfrom
only21mil:manual-grub-fnmode-mkinitcpio
Nov 9, 2026
Merged

scottjones merged 1 commit into
omacom:mainfrom
only21mil:manual-grub-fnmode-mkinitcpio

Conversation

@only21mil

Copy link
Copy Markdown
Contributor

Problem

The Keyboard and trackpad page tells every owner who wants F1 to F12 first to write options hid_apple fnmode=2 and run sudo omarchy-mac-boot-update. On a Mac that still boots GRUB, that command only runs update-grub (omarchy-mac-boot/bin/omarchy-mac-boot-update, the omarchy-mac-limine-active branch). hid_apple loads from the initramfs with the options it was built with, so the initramfs keeps the old mode and the top row never changes. GRUB Macs still exist, as #48 and #77 show.

The rest of the repo already says the right thing. The omarchy-mac README gives sudo mkinitcpio -P, or sudo omarchy-mac-boot-update on a Limine Mac. omarchy-mac-setup-keyboard does the same: omarchy-mac-boot-update when omarchy-mac-limine-active passes, mkinitcpio -P otherwise.

Change

One sentence in mac-manual/content/06-keyboard.md. It now says to rebuild the boot image with sudo omarchy-mac-boot-update on a Mac that boots Limine, or sudo mkinitcpio -P on an older Mac that still boots GRUB, and that the setting takes effect at the next boot. Limine owners follow the same command as before.

Scope and approval

Docs only. No code changes, because the code already rebuilds the right image on both boot loaders; only the manual was wrong. No omarchy-mac version bump, since no package behaviour changes. Nothing boot-critical changes, so no cold-boot evidence applies. The rest of the page is unchanged.

Verification

  • python3 mac-manual/diagrams/gen.py, then git status --porcelain -- mac-manual/diagrams: exit 0, no diff, on base and candidate.
  • python3 mac-manual/build.py with markdown==3.7: "built 14 pages into mac-manual/dist", exit 0, on base and candidate. The builder checks every link.
  • .github/scripts/check-scope and .github/scripts/check-architecture-gates: exit 0.
  • Diffing the base and candidate dist/ trees: only keyboard/index.html changes.
  • Read in omacom/omarchy-pkgs: on any Mac, the limine-mkinitcpio-hook wrapper at /usr/local/bin/mkinitcpio passes limine-apple-gate --mac and execs plain /usr/bin/mkinitcpio, so sudo mkinitcpio -P rebuilds the /boot initramfs that GRUB boots.

The keyboard page built from main, before this change:

Keyboard page on main, telling every Mac to run omarchy-mac-boot-update

The same page built from this branch:

Keyboard page on this branch, with omarchy-mac-boot-update for Limine Macs and mkinitcpio -P for GRUB Macs

Not checked

  • Changing fnmode on a real GRUB Mac and on a real Limine Mac. The claim rests on the code paths named above.
  • The package and integration suites, which this change does not touch.

Prior PRs

None make this change. #6, #8 and #105 touch the keyboard and the omarchy-mac README, not this page.

Generated with Claude Opus 5.5 and GPT-6.1 Sol in T3 Code Nightly

The keyboard page told every owner to run omarchy-mac-boot-update after
writing an hid_apple fnmode option. On a Mac that still boots GRUB that
command only runs update-grub, so the initramfs that loads hid_apple keeps
the old mode. Name mkinitcpio -P there, as the omarchy-mac README and
omarchy-mac-setup-keyboard already do, and keep omarchy-mac-boot-update for
Limine Macs, whose UKI it rebuilds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@scottjones scottjones left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, good catch. GRUB Macs do need mkinitcpio -P here, because omarchy-mac-boot-update only runs update-grub on them. This now matches omarchy-mac-setup-keyboard and the README.

@only21mil

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

@scottjones, thank you for the review, and for checking it against omarchy-mac-boot-update. Confirming that it only runs update-grub on a GRUB Mac is what makes mkinitcpio -P the right step there, so the manual now gives the same advice as omarchy-mac-setup-keyboard and the README.

@scottjones
scottjones merged commit 20a15ab into omacom:main Nov 9, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants