docs: add generic dotfile update guide

astro.config.mjs

@@ -690,6 +690,10 @@ export default defineConfig({
               },
               link: 'configuration/enabling_hardware_acceleration_in_google_chrome',
             },
+            {
+              label: 'Updating Desktop Dotfiles',
+              link: 'configuration/update_dotfiles',
+            },
             {
               label: 'Desktop Environments',
               items: [{ autogenerate: { directory: 'configuration/desktop_environments' } }],

src/content/docs/configuration/desktop_environments/hyprland.mdx

@@ -4,8 +4,6 @@ description: Common tasks to do after installation and keybinds overview
 ---
 
 import { Kbd } from 'starlight-kbd/components'
-import ImageComponent from '~/components/image-component.astro';
-import { Aside } from '@astrojs/starlight/components';
 
 :::note
 Hyprland is a wayland compositor that supports various layouts such as dwindle (tiling), scrolling, master, monocle, and custom layouts. It is **not** a full desktop environment (DE).
@@ -173,33 +171,18 @@ https://github.com/CachyOS/cachyos-hypr-noctalia/releases
 
 ### Hypr updates
 
+For the general process of comparing and selectively updating files from `/etc/skel`, see [Updating Desktop Dotfiles](/configuration/update_dotfiles). The steps below cover the Hyprland-specific migration details.
+
 :::note
 Once you migrate your keybinds from v4 to v5, they will no longer work to call Noctalia IPC calls.
 :::
 
-1. Install `meld` if you don't have it (`pacman -Q meld` to check if you have it).
-1. Run `meld /etc/skel/.config/hypr ~/.config/hypr`.
-1. From meld you will see an overview of all the files with changes. Blue files have changes, while green files are net new.
-    <br />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/meld_overview.png')} />
-1. Click into a blue file to see changes to be applied. You can use your best judgement to determine what to apply, but if you haven't made any changes, it's safe to overwrite the whole file. Click the arrow to apply changes and the x to remove old lines.
-    <Aside type="note">Make sure to not overwrite things you may have changed such as your monitor settings.</Aside>
-    <br />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge.png')} />
-1. You can merge all as well.
-    <br />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge_all_1.png')} />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge_all_2.png')} />
-1. When you're finished with your changes for the file, save and exit.
-    <br />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/save_exit.png')} />
-1. The net new green files will ask where you want to save it. You can save it in `~/.config/hypr/config/` with the same name. There are 4 new files.
-    * defaults.lua is now variables.lua. You must manually move any custom additions/changes to the new file.
-    * keybinds.lua is now binds.lua. You must manually move any custom additions/changes to the new file.
-    * input.lua is now inputs.lua. You must manually move any custom additions/changes to the new file.
-    * workspaces.lua is new net and can be cleanly moved over without changes.
-    <br />
-    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/workspaces.png')} />
+The v4-to-v5 migration adds four files under `~/.config/hypr/config/`. When saving new files from the comparison, use these names and manually move any personal changes:
+
+* `defaults.lua` is now `variables.lua`.
+* `keybinds.lua` is now `binds.lua`.
+* `input.lua` is now `inputs.lua`.
+* `workspaces.lua` is new and can be copied over without changes if you have not customized it.
 
 ### Noctalia Updates
 

src/content/docs/configuration/update_dotfiles.mdx

@@ -0,0 +1,36 @@
+---
+title: Updating Desktop Dotfiles
+description: Compare and selectively update personal configuration from CachyOS settings packages
+---
+
+Settings packages for desktop environments and window managers install their default user files in `/etc/skel`. When one of these packages is updated, compare the new defaults with your existing files before applying changes.
+
+## Compare a file or directory
+
+Install `meld` if it is not already installed, then compare the relevant paths. For example, for Hyprland or Niri:
+
+```sh
+meld /etc/skel/.config/hypr ~/.config/hypr
+meld /etc/skel/.config/niri ~/.config/niri
+```
+
+You can also compare individual files, or compare the complete template and home directories:
+
+```sh
+meld /etc/skel/.config/niri/config.kdl ~/.config/niri/config.kdl
+meld /etc/skel ~
+```
+
+Use the path supplied by the `cachyos-*-settings` package for your desktop environment or window manager. The package’s files may cover more than its main configuration directory, so check the package’s `/etc/skel` tree when looking for other updates.
+
+:::caution
+Comparing `/etc/skel` with `~` recursively can be noisy and resource-heavy. Comparing only the relevant configuration directory or file is usually easier to review.
+:::
+
+## Review changes in Meld
+
+In a directory comparison, open changed files to inspect the differences and use Meld’s merge controls to copy individual changes in the required direction. For a recursive comparison, use the comparison status filter and hide **New** files when you want to focus on existing files that changed. Restore the **New** filter when checking whether the updated defaults add files you may want to copy.
+
+Review each change before saving it. Your configuration can contain personal settings, hardware-specific values, or changes that are not present in the package defaults. Do not blindly overwrite your home directory or merge every change; keep, adapt, or reject each change as appropriate.
+
+The existing [Hyprland dotfile migration instructions](/configuration/desktop_environments/hyprland/#migrating-from-v4-dots-to-v5-updating-your-dots) provide a desktop-specific example of this process.