garuda-migrations

garuda-migrations applies configuration changes that Garuda Linux needs on existing systems. It runs after pacman installs or upgrades the garuda-migrations package, so the changes come with the update. The package keeps a version number. The runner applies only the migrations that are newer than the version the system last applied.

Files and hooks

Path	Purpose
/usr/share/libalpm/hooks/00-garuda-migrations.hook	Runs the migration runner after the transaction.
/usr/share/libalpm/hooks/95-garuda-migrations.hook	Runs the post runner after the transaction.
/usr/share/libalpm/scripts/garuda-migrations-runner	Applies the system and user migrations.
/usr/share/libalpm/scripts/garuda-migrations-runner-post	Records the applied version and applies the display manager migration.
/usr/share/garuda/migrations/current_version	The version of the installed package, in the form pkgver-pkgrel. Currently 4.1.0-1.
/etc/garuda/migrations/applied_version	The version the system last applied. Written by the post runner.
/etc/garuda/migrations/has_legacy_patches	Flag file that switches garuda-config-agent to legacy start levels.

Both hooks run as PostTransaction and trigger on Install and Upgrade of the garuda-migrations package. They run only when that package is part of the transaction. The runner reads the ISO release file /usr/lib/garuda/garuda-release for the TIMESTAMP and CODENAME values.

How a run works

1. The runner 00 reads applied_version. When the file is missing, the system counts as a new install and the applied version is 0.0.0.
2. For each migration, the runner checks vercmp <migration version> <applied version>. It runs the migration only when the migration version is newer. Most migrations also require IS_NEW_INSTALL to be false, so a new install skips them.
3. The runner then runs the user migrations. It loops over the accounts from getent passwd. It skips system accounts (UID below 1000 and UID 65534), accounts without a home directory and accounts without a login shell. For each remaining user, it runs the user migrations in the user’s home directory.
4. The post runner 95 writes the current version to applied_version first. It then applies the display manager migration.
5. Notices from the migrations are added to /var/lib/garuda/tmp/update_notices. garuda-update prints them after the update and deletes the file.

Note

The runner writes applied_version in the post runner, not in the first runner. If the post runner does not run, the applied version stays old, and the next upgrade checks the same migrations again.

Migrations

The code gates each migration by version, not by date. The table lists the gate version in the order the runner checks them. Migrations marked as user migrations run in every user’s home directory.

System migrations

Gate	What it does
1.1.0-1	Removes /etc/sddm.conf.d/01-garuda-fix-dpi.conf.
1.2.0-1	Adds /.snapshots to PRUNEPATHS in /etc/updatedb.conf.
1.3.0-1	Adds grub-btrfs-overlayfs to the HOOKS line of /etc/mkinitcpio.conf.
1.4.0-1	Adds deny = 10 to /etc/security/faillock.conf when no deny line exists, and shows a notice.
2.1.0-1	Comments out GRUB_DISABLE_RECOVERY=true in /etc/default/grub to enable the recovery menu entry, and shows a notice.
2.2.0-1	Removes the ibt=off kernel parameter from GRUB_CMDLINE_LINUX_DEFAULT.
2.3.1-1	Changes the plymouth hooks in /etc/mkinitcpio.conf to the new names. Changes the display manager from the plymouth variant to the normal service, and shows a notice.
2.4.1-1	Removes the splash kernel parameter from GRUB_CMDLINE_LINUX_DEFAULT, and shows a notice.
2.5.2-1	Shows a notice about the switch from mlocate to plocate and the .pacsave file of /etc/updatedb.conf.
2.6.0-1	Removes /etc/polkit-1/rules.d/49-nopasswd-live.rules when the system is not a live system.
3.0.1-1	Disables the global psd.service user service and shows a notice.
3.1.0-1	Creates /etc/systemd/do-not-udevadm-trigger-on-update to prevent crashes on some hardware, and shows a notice.
3.2.0-1	Changes WaylandEnable=false in /etc/gdm/custom.conf back to the default, and shows a notice.
3.3.0-1	Adds systemd to the passwd, group, shadow and gshadow lines of /etc/nsswitch.conf, and shows a notice.
3.4.1-1	Removes the drop-in logic for /etc/default/grub.d from /etc/default/grub, and shows a notice.
3.4.3-1	Changes the SDDM theme from Sweet to Sweet6 when the Sweet6 theme is installed, and shows a notice.
3.5.2-1	Creates /etc/garuda/migrations/has_legacy_patches, and shows a notice about the new pacnew handling.
3.6.0-1	Shows a notice about the refreshed KWin blur settings.
3.6.1-1	Removes ddcutil from IgnorePkg in /etc/pacman.conf, and shows a notice.
3.7.0-1	Shows notices about the replacement of an older Garuda application by Garuda Toolbox when Toolbox is installed. Shows a notice for a Dr460nized blur fix on the ISO build dated 260308.

User migrations

Gate	What it does
3.0.0-1	Replaces the fastfetch --load-config calls in ~/.config/fish/config.fish.
3.5.0-1	Replaces the cat alias in ~/.config/fish/config.fish with an abbr.
3.6.0-1	Rewrites the blur effect sections in ~/.config/kwinrc for Dr460nized and Mokka.
3.7.0-1	Enables better_blur_dxEnabled in ~/.config/kwinrc for Dr460nized on the ISO build dated 260308.
4.0.0-1	Replaces an unchanged ~/.bashrc and an unchanged ~/.config/fish/config.fish with the new Garuda versions. The check uses known MD5 hashes, so a changed file is kept.
3.7.1-1	Removes the --color and --icons flags from eza aliases in fish and bash.
3.7.2-1	Removes ~/.config/fish/conf.d/done.fish when the system copy in /usr/share/fish/vendor_conf.d/ exists.
4.1.0-1	Converts an old ~/.config/hypr/hyprland.conf to Lua with hyprlang2lua when that package is installed. The old file is kept as hyprland.conf.garuda-backup.

Post migration

Gate	What it does
4.0.2-1	When sddm.service is enabled and the Mokka or Dr460nized profile is installed, moves the login screen to Plasma Login Manager. Copies the user’s Plasma settings, sets a wallpaper, disables sddm.service and enables plasmalogin.service. Skipped when /etc/plasmalogin.conf already exists.

Caution

The Plasma Login Manager migration disables SDDM and needs a reboot to take effect. The notice printed after the update tells you to reboot.

Developer rules

The readme.txt in the package states two rules for new migrations. Each change must have a way to be reverted in a later version, for example with a comment or a custom file name. Each change must be applied only once, so a setting that the user changed later is not overwritten again.

garuda-hotfixes

garuda-hotfixes is no longer part of the package set. The status below comes from the code and the changelog.

• The repository tree has no garuda-hotfixes PKGBUILD in pkgbuilds/. The last source is in archive/PKGBUILD/garuda-hotfixes/, at version 1.1.2. Its post_upgrade rewrote /usr/bin/update for the old remote fix and changed autodefrag to noautodefrag in /etc/fstab.
• The changelog entry “Implement new emergency hotfixes system, ditch garuda-hotfixes” for garuda-update replaces the package with the emergency hotfix in garuda-update. The emergency hotfix is described in garuda-update fixes.
• The changelog entry “Auto uninstall garuda-hotfixes via intervention sequence” is in the same release. The post-update step of garuda-update removes the package when the intervention sequence is below 2. See garuda-update fixes.
• The changelog entry “Remove garuda-hotfixes” is in the Cosmic section of the same release. It removes the package from the Cosmic package list. It does not by itself describe the removal from the other editions.
• garuda-health lists garuda-hotfixes as a deprecated package. When it is installed, the check reports a LOW issue with a fix that removes it.
• The garuda-hotfixes-version endpoint on the Garuda web server returns HTTP 410 with the text “Feature removed in Garuda System Maintenance 3.1.0”. This is the web server configuration in the repository. The live response is UNCONFIRMED.
• Archived packages in archive/ still refer to the package.