Porting to a New Distro

Porting to a New Distro

This is a condensed walkthrough of stamping a new Linux OS repo from the dotfiles-Fedora template. The full reference — package-manager command tables, per-tool package names across distros, and the clipboard-backend matrix — lives in PORTING-MATRIX.md.

The key insight: the structure is identical every time. Only three things change per distro: package-manager commands, package names, and distro quirks. Core never changes (it's vendored).

The per-repo recipe

1. cp -r dotfiles-Fedora dotfiles-<Distro>
2. Rename os/fedora.zsh → os/<distro>.zsh; swap the clipboard + package-manager aliases.
3. Replace install/packages.txt with that distro's package names (see the matrix table).
4. In bootstrap.sh: swap the dnf block for the distro's installer and the /etc/os-release guard string.
5. git subtree add --prefix=core <dotfiles-core> main --squash
6. Update the README's "specifics" section to that distro's quirks.

Distro quirks that will actually bite you

These are the gotchas worth a README note on each target (full detail in the matrix):

• Arch — rolling; update fully or not at all (never -Sy <pkg> without -u — partial upgrades break things). Most tools are in official repos; the rest are an AUR paru -S away.
• openSUSE — two flavors with different update commands: Tumbleweed uses zypper dup, Leap uses zypper up. Add the Packman repo for codecs.
• Alpine — the real outlier: musl libc, not glibc, so glibc-linked prebuilt binaries won't run (prefer apk or musl builds). Default shell is ash, privilege tool is doas, many commands are busybox applets.
• Gentoo — source-based: emerge compiles, so expect build time (use a binhost + tune MAKEOPTS). USE flags gate features at compile time.
• Kali (WSL2) — not stamped from Fedora; Debian-family with an offensive role layer. Debian renames binaries (bat→batcat, fd-find→fdfind; Core handles both), and WSL2 is NAT'd — a reverse shell isn't LAN-reachable until you enable mirrored networking in the Windows-side %UserProfile%\.wslconfig.

Cross-distro detail Core already handles

Two behavior-affecting differences are resolved in Core's tools.zsh, so you don't branch on them in the OS layer:

• Renamed binaries — fd→fdfind and bat→batcat on Debian/Kali are resolved to $FD_BIN / $BAT_BIN, used everywhere (aliases, fzf previews).
• Graceful degradation — any tool absent on a box falls back to the classic command, so a bare/minimal distro install still works.

Repo status

All template stamps are complete: core, Fedora (template), MacBook, Arch, openSUSE, Alpine, Gentoo, Kali. Kali (apt + offensive) and MacBook (Homebrew) are their own lineages, built directly rather than stamped.

See also

• Consuming Core in an OS Repo — the subtree vendoring step.
• PORTING-MATRIX.md — the full command/package/clipboard tables.