sxmo_migrate.sh(1)

💅 sxmo_migrate.sh — your migration bestie (General Commands Manual)

okay so picture this: it's sxmo_migrate.sh, and it lives in the General Commands Manual section, and honestly? it's the friend who shows up with a label maker when your config files are a mess. let's get into it 🫶

---

✨ SYNOPSIS ✨

sxmo_migrate.sh [subcommands...]

that's it. that's the whole vibe. you just throw subcommands at it and it handles the rest 💖

---

🎀 SUBCOMMANDS 🎀

• reset — nukes your config files and hooks back to the defaults. like, all of them. bestie please be careful with this one 😭 it's literally a last resort for when your system is so broken you need to start over. everything of yours gets moved out of the way and flagged for migration. not deleted, just... relocated. still scary though.
• state — the vibe check 📋 reports whether you've got any config files or hooks pending migration. that's it. yes/no energy.
• sync — tells it to go check the versions of your config files and hooks. fun fact: this runs automatically when Sxmo starts, so you don't usually have to think about it ✨
• sync state — the combo meal 🍓 use this right after you just finished a migration but didn't restart the system yet. it's giving "I did the work, now acknowledge it."

---

🌸 DESCRIPTION 🌸

so while the sxmo devs are developing sxmo (as one does), they regularly update certain config files — think the xinit/sway template, the hooks, whatever. and here's the thing: those files are typically a mixture of changes from the devs and customizations from you, the user. that mixture is literally the whole point — it gives you maximum flexibility to adapt Sxmo to your liking 👑

but when they update those files, the challenge is making sure your modifications can be easily merged back in again. and like, more importantly, that the system is never in a broken state because of outdated configurations and version mismatches. no cap.

so here's how it goes down: whenever your config files are out-of-date when starting Sxmo, they get moved aside (i.e. renamed with a .needs-revision extension, cute) and the default configuration takes its place. this keeps the system always functional and means no conflicts should arise. a red notification will pop up telling you that you have configuration files that need migrating. not subtle. on purpose. 🔥

the actual migration is done by running a script named sxmo_migrate(1). you can launch it straight from the configuration menu or over ssh (recommended, fr fr). it first shows you the differences between your config and the new default, then lets you edit and apply your config accordingly. if you have delta(1) or colordiff(1) installed, they get used to show the diff — fancy ✨ in the edit stage, sxmo_migrate(1) uses $DIFFTOOL to help you merge your changes. by default $DIFFTOOL is set to vimdiff. if that's not available, your regular $EDITOR gets used instead.

if you have any pending migrations, always make sure you complete the migration process before making any new changes to your configuration. seriously. and it's also recommended to keep your config under version control (e.g. git) — future you will thank present you 💜

Note: the order of the diff arguments can be changed by setting environment variable $SXMO_MIGRATE_ORDER to "user:system", instead of the default "system:user". it can also be toggled at runtime. iykyk.

---

🧚 TECHNICAL DETAILS 🧚

Sxmo uses explicitly versioned config files, meaning each one carries a simple version hash unique to that file. that version hash lives in a comment in the file itself, like so:

# configversion: d8aaf01c9489793bda3686ef23b2b192

you should only update this version hash when sxmo_migrate.sh prompts you to do so by showing a diff of a newer configversion hash. that's the whole rule. this info is what determines whether your custom config is up-to-date with the system-supplied defaults 💅

🌈 RESOLVING SYSTEM CONFIGURATIONS ON SYSTEM UPGRADE AND MAKE

apk(1), on postmarketOS, will install new configs as .apk-new on upgrades if you've modified the original config in /etc. also, when hacking on Sxmo, you'll often run make install and that may modify a config in /etc from apk's perspective. you can merge apk's config changes by running doas update-conf. you can also run apk audit to list all the files that have changed from what apk originally installed. chef's kiss, problem solved 🎀

---

⭐ ENVIRONMENT ⭐

sxmo_migrate(1) reads the following environment variables:

• DIFFTOOL — the diff tool to use for editing and resolving migrations (not for display 👀 those are different jobs).
• SXMO_MIGRATE_ORDER — can be set to "user:system" or "system:user" (default). determines the order in which arguments are passed to diff, and therefore how results are colored 🌈

---

🦋 SEE ALSO 🦋

sxmo(7)

---

and that's the whole page, bestie 💖 this was General Commands Manual energy, version sxmo_migrate.sh(1), dated 2026-05-10 — go migrate something and slay ✨👑