path: root/MIGRATION.md

# Migrating guix-dotfiles onto nix-combined

This repo supersedes `guix-dotfiles/home-config/nix-home-manager` (the ad-hoc
home-manager flake guix-dotfiles was already using) and pulls Linux desktop
config that used to live in `guix-dotfiles/home-config/home-configuration.scm`
into home-manager proper. It does **not** replace Guix itself: package
management, the system config, and three specific home services stay in
Guix (see "Stays in Guix" below).

`nix-combined` is deliberately its own repo (own history, own remote) so
that darwin machines never need to clone anything guix-related. It's wired
into `guix-dotfiles` as a **git submodule** at
`guix-dotfiles/home-config/nix-combined` - the rest of this section covers
that wiring; everything after "Stays in Guix" is still a plan for you to
apply by hand.

## 1. Submodule wiring (already done in this working tree)

Already applied, not yet committed/pushed - review with `git status`/`git
diff` in `guix-dotfiles` before committing:

- `guix-dotfiles/.gitmodules` added, pointing `home-config/nix-combined` at
  **the local filesystem path** to this checkout of `nix-combined`. That
  only works on this machine. **Before pushing**, create the real remote
  (recommend `https://git.rschanz.org/nix-combined`, matching the
  `nix-dotfiles`/`guix-dotfiles` naming convention) and push `nix-combined`
  there, then run, from `guix-dotfiles`:
  ```
  git submodule set-url home-config/nix-combined https://git.rschanz.org/nix-combined
  git add .gitmodules
  git commit
  ```
- `home-configuration.scm`'s `%home-symlinks` now points
  `.config/guix/home-config/nix-combined` at `.config/home-manager`
  (previously `.config/guix/home-config/nix-home-manager`).
- `deploy.sh`'s fresh-install clone now uses `git clone --recurse-submodules`
  so a from-scratch deploy pulls `nix-combined` in the same step.

**On existing machines**, after pulling this change:
```
git submodule update --init --recursive
```
(or `git clone --recurse-submodules` next time you clone `guix-dotfiles`
fresh). Then switch with `home-manager switch --flake ~/.config/home-manager#ryan`
(the `rebuild` zsh alias does this on Linux).

**Updating `nix-combined` later**: since the submodule pins an exact commit,
pulling new `nix-combined` changes needs a bump in `guix-dotfiles`:
```
cd home-config/nix-combined && git pull origin main && cd -
git add home-config/nix-combined
git commit -m "bump nix-combined"
```

The old `guix-dotfiles/home-config/nix-home-manager` directory (the
pre-submodule ad-hoc flake) can be deleted once you've confirmed the new
one builds and switches cleanly.

**Leave the `nix-config` symlink entry alone for the first switch.** It's
what sets `experimental-features = nix-command flakes` for your user today,
which is what lets `home-manager`/`nix` read this flake at all -
home-manager can't bootstrap its own prerequisite. `linux.nix` now writes
its own `~/.config/nix/nix.conf` and `~/.config/nix/registry.json` via
`xdg.configFile`, so *after* the first successful switch, remove the
`nix-config` entry from `%home-symlinks` too - otherwise HM's files resolve
through that symlink and land as untracked files inside the guix-dotfiles
checkout instead of in the Nix store.

## 2. Remove entries `home-configuration.scm` now duplicates

Once nix-combined delivers a path, Guix must stop also writing it, or
activation will collide (two things trying to own the same symlink target).
In `home-configuration.scm`'s `home-xdg-configuration-files-service-type` and
`home-files-service-type`, remove these lines (nix-combined now owns them):

- `"nvim/init.vim"`, `"nvim/after/ftplugin/markdown/custom.vim"`,
  `"nvim/after/ftplugin/mail/custom.vim"` - nix-combined's neovim config
  (lazy.nvim-based, in `users/ryan/modules/nvim`) is the canonical one now;
  the old vim-plug based `nvim/config/init.vim` + `plug.vim` is superseded.
- `"hypr/monitors.conf"`, `"hypr/pyprland.toml"`, `"hypr/family_guy.mp4"`,
  `"hypr/hyprlock.conf"`, `"hypr/hypridle.conf"`, `"hypr/kanshi.conf"`,
  `"hypr/subwaysurfer.webm"`, `"hypr/scripts"` (the `hyprland.conf` itself
  was already coming from the old nix-home-manager flake, unchanged in
  spirit here - just re-homed)
- `"wpaperd"`, `"mpv"`, `"foot"`, `"waybar"`, `"alacritty"`, `"aerc"`
- `"pulse/client.conf"`
- `.local/share/nvim/site/autoload/plug.vim` (dead once nvim is lazy.nvim-based)
- `.local/share/mailvelope`, `.mozilla/native-messaging-hosts/tridactyl.json`,
  `.local/share/tridactyl`
- **`.icons`** (from `home-files-service-type`) - this one isn't optional
  cleanup, it's a hard prerequisite. Guix delivers `.icons` today as a
  single recursive `local-file` symlink, but `linux.nix`'s
  `home.pointerCursor` (with `x11.enable = true`) needs to write
  `~/.icons/default/index.theme` itself. With the old symlink still in
  place, HM can't create a file inside a symlinked-to-store directory and
  activation fails outright. Remove this entry before your first
  `home-manager switch`.
- `.gitconfig` (nix-combined's `programs.git` now owns this, with the
  `filter.lfs` and `[sendemail]` sections merged in - they existed in
  guix-dotfiles' `.gitconfig` but were missing from the old nix-dotfiles config)
- `.ssh/config` (same story - nix-combined's `programs.ssh.settings` is a
  strict superset: added the `linode` host, the `192.168.216.1`
  legacy-algorithm host, the `KexAlgorithms` exclusion on `Host *`, and the
  `Match host * exec "gpg-connect-agent ..."` line)
- `.docker/cli-plugins` (docker-compose plugin - if you still want this,
  it's cheap to add to `users/ryan/linux.nix`'s `home.file`; it wasn't
  carried over because nothing else referenced it and I didn't want to
  guess at whether you still use it)

`hypr/Wallpapers` and the sway config were left alone deliberately - you said
you'd handle wallpapers yourself, and `sway` isn't referenced by anything
active (Hyprland is the real WM; see "Dead/unused" below).

## 3. Switch the login shell to zsh

`guix-dotfiles/modules/ryan-config/base-system.scm`'s `base-operating-system`
has:

```scheme
;(shell (file-append zsh "/bin/zsh"))
```

commented out, so your account's login shell is still bash even though the
canonical config (nix-dotfiles, and now nix-combined) is zsh. Uncomment that
line (and rebuild/reconfigure the system) so `programs.zsh` in
`users/ryan/common.nix` is actually what runs on login. Until you do, bash
still runs (Guix's `home-bash-service-type` config, if still present, keeps
working - just don't remove it from `home-configuration.scm` until the shell
is actually switched, or you'll drop to a shell with no rc file at all).

## Stays in Guix - no home-manager equivalent without systemd

Home-manager's `services.*` modules assume a systemd user session to
autostart things (or launchd on macOS). Guix uses shepherd instead, and
home-manager has no shepherd backend. These three keep running exactly as
they do today, defined in `guix-dotfiles/modules/ryan-services/`:

- **`home-pipewire-service-type`** (pipewire + wireplumber daemons)
- **`home-dbus-service-type`** (per-user session dbus, since Guix has no
  systemd --user to provide one)
- **`downloads-garbage-collector-service-type`** (the weekly Downloads
  cleanup shepherd timer)

`home-gpg-agent-service-type` is the one service that *did* migrate cleanly:
gpg-agent doesn't need a supervisor. It's socket-activated the same way on
both platforms via the zsh init in `common.nix`
(`gpgconf --launch gpg-agent` + exporting `SSH_AUTH_SOCK`), which is exactly
what nix-dotfiles' darwin config already did. `linux.nix` points
`services.gpg-agent.pinentry.package` at nixpkgs' `pinentry-qt` rather than
Guix's system profile path, so it isn't cross-dependent on Guix.

`home-spotifyd-service-type` is already commented out/disabled in
`home-configuration.scm` - nothing to do there.

## Dead/unused - candidates to delete from guix-dotfiles

Found while comparing the two repos; none of these are referenced by
anything active, so nothing carried them into nix-combined:

- **fish** (`home-config/fish/`) - the `fish` package is commented out of
  `home-configuration.scm`'s package list, but the dotfiles are still
  checked in. Orphaned.
- **`.nix-channels`** - classic (non-flake) nix-channel file. Now that
  everything is flake-based, this shouldn't be needed.
- **`icons/XCursor-Pro-Dark*`** - not referenced anywhere; only
  `Bibata-Modern-*` appears in `hypr/hyprland.conf`.
- **`fonts/Fira Code`, `fonts/Lilex`, `fonts/Monofur For Powerline`,
  `fonts/AnonymicePro`, `fonts/MonofurNerdFont`** - superseded by
  `nerd-fonts.{fira-code,lilex,anonymice,monofur}` from nixpkgs
  (`linux.nix`'s `home.packages`), which ship the same font families.
- **`home-spotifyd-service-type`** usage - already disabled.
- **`alacritty`** - config exists in both repos, but no package installs the
  `alacritty` binary in either the guix or the old nix-home-manager config.
  `foot` is what's actually wired into the system (Guix package list,
  kmscon login). I added `pkgs.alacritty` to `linux.nix` so the config isn't
  dead weight, but confirm whether you still use it - if not, drop both the
  package and `users/ryan/linux/alacritty/`.
- **`sway` config** - not referenced by anything; Hyprland (via
  home-manager) is the actual compositor in use.

## Additive merges (things nix-dotfiles was missing, now fixed)

- **aerc**: `signature_personal`, `signature_rit_personal`,
  `templates/quoted_reply`, `templates/thanks` existed only in
  guix-dotfiles' aerc config, even though `accounts.conf`/`aerc.conf`
  already referenced them by path. Copied into `users/ryan/aerc/`.
- **git**: `filter.lfs` and `[sendemail]` sections, merged into
  `common.nix`'s `programs.git.settings`.
- **ssh**: `linode`, `192.168.216.1` (legacy host key/pubkey algorithms),
  the `KexAlgorithms` exclusion, and the `Match host * exec ...` line,
  merged into `common.nix`'s `programs.ssh`.

## Linux desktop stack re-pin (see also the flake-version conversation)

The old `guix-dotfiles/home-config/nix-home-manager/flake.nix` pinned
home-manager to a 2024 commit specifically so it'd match separately-pinned
`hyprland`/`hyprlock`/`hyprpicker`/`wpaperd` flake inputs (plus a
`ryan77627/nixGL` fork and a `rust-overlay` pin for wpaperd). Sharing
`common.nix` with the darwin config (which tracks home-manager master)
required moving Linux onto the same nixpkgs/home-manager as darwin.

The good news: current nixpkgs-unstable now packages `hyprland` (0.52.2),
`hyprlock`, `hypridle`, `hyprpicker`, `wpaperd`, `kanshi`, and `pyprland`
directly, so those five extra flake inputs (and the rust-overlay pin) are
gone entirely - `linux.nix` just uses `pkgs.hyprland` etc. Only two
Linux-specific flake inputs remain in `flake.nix`:

- `nixgl` (still needed - it exists specifically to patch Guix's mesa/GL
  mismatch, unrelated to nixpkgs version)
- `clipboard-sync` (not in nixpkgs)

**Dropped**: the `hypr-dynamic-cursors` Hyprland plugin (animated cursor
trails). It has no nixpkgs package and pinning a matching flake input just
for one cosmetic plugin didn't seem worth the added re-pin risk. If you want
it back, add it as a flake input with `inputs.nixpkgs.follows = "nixpkgs"`
and pass it as a plugin in `wayland.windowManager.hyprland.plugins`.

**Dropped**: `mozff` (firefox-nightly flake) - unused. The
`firefox-nightly` module's package line was already commented out in the
guix config; it just configures `programs.firefox` (nixpkgs' own package).

**Cursor theme changed**: the vendored `Bibata-Modern-Classic-Hyprland` /
`Bibata-Modern-daed9-v1.0.2-x11` asset had oddly-versioned internal theme
names from however that release was originally packaged. Replaced with
nixpkgs' `bibata-cursors` (`home.pointerCursor` in `linux.nix`) - the
`HYPRCURSOR_THEME`/`XCURSOR_THEME` env vars in `hyprland.conf` were updated
to the plain name `Bibata-Modern-Classic` to match. nixpkgs' build doesn't
have a `-Hyprland`-suffixed hyprcursor variant; Hyprland falls back to
rendering the XCursor theme directly, which works fine, just without the
optional cleaner hyprcursor rendering path.

## Verification note

`homeConfigurations.ryan` was checked with:

```
nix eval --raw .#homeConfigurations.ryan.activationPackage.drvPath
```

which forces full module evaluation (catches missing options and
darwin-only packages referenced on Linux) without building anything.

`darwinConfigurations.RyanMac` could not be evaluated on this machine (no
aarch64-darwin builder). It was verified by structural diff instead:
`flake.nix`'s darwin-facing inputs/outputs, `hosts/RyanMac/configuration.nix`,
and `modules/darwin/random-wallpaper` are unchanged from `nix-dotfiles`;
`common.nix`/`darwin.nix` reproduce `nix-dotfiles/users/ryan/home.nix`
line-for-line except where noted above. Please run
`darwin-rebuild build --flake .#RyanMac` yourself before switching for real.