dot/MIGRATION.md

# Migration Guide: Channels → Flakes

## Why Migrate to Flakes?

✅ **Reproducibility**: Lock files pin exact package versions
✅ **Latest unstable packages**: Easy access to nixos-unstable
✅ **Better for dotfiles**: Version control with exact dependencies
✅ **Modern approach**: Future of Nix configuration
✅ **You're ready**: You already have flakes enabled!

## Current State (Channels)

Your current setup:
```bash
/etc/nixos/configuration.nix  # Channel-based, imports from <nixos-wsl/modules>
```

Commands:
```bash
sudo nix-channel --update
sudo nixos-rebuild switch
```

## Target State (Flakes)

New setup:
```bash
/home/pan/dev/config/dot/nix/nixos/
├── flake.nix           # Declares inputs (nixpkgs, nixos-wsl, home-manager)
├── configuration.nix   # System config (no imports needed)
├── home.nix           # Your user config
└── modules/           # User modules
```

Commands:
```bash
nix flake update  # Update dependencies
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix
```

## Migration Steps

### Step 1: Test the Flake Configuration

First, let's make sure it builds without applying:

```bash
cd /home/pan/dev/config/dot/nix/nixos
nix flake check --impure  # Validate syntax
sudo nixos-rebuild build --flake .#nix --impure  # Test build
```

If successful, you'll see a `result` symlink. The `--impure` flag is needed for NIX_LD settings.

### Step 2: Review What Will Change

Compare your current and new configs:
```bash
diff /etc/nixos/configuration.nix /home/pan/dev/config/dot/nix/nixos/configuration.nix
```

Key differences:
- ❌ Removed: `imports = [ <nixos-wsl/modules> <home-manager/nixos> ]`
- ✅ Added: Flake manages these as inputs
- ✅ Uses: nixos-unstable (latest packages)
- ✅ Locks: Exact versions in flake.lock

### Step 3: Apply the Flake Configuration

**Option A: Direct (Recommended)**
```bash
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure
```

**Option B: Symlink to /etc/nixos (Optional)**
```bash
sudo mv /etc/nixos/configuration.nix /etc/nixos/configuration.nix.backup
sudo ln -s /home/pan/dev/config/dot/nix/nixos/flake.nix /etc/nixos/flake.nix
sudo ln -s /home/pan/dev/config/dot/nix/nixos/configuration.nix /etc/nixos/configuration.nix
sudo nixos-rebuild switch --flake /etc/nixos#nix --impure
```

### Step 4: Verify Everything Works

After switching:
```bash
# Check system info
nixos-version

# Check flake info
nix flake metadata /home/pan/dev/config/dot/nix/nixos

# Test your tools
zsh --version
tmux -V
nvim --version
git --version
task --version
```

### Step 5: Set Up Convenient Alias (Optional)

Add to your shell config:
```bash
alias nixos-update='cd /home/pan/dev/config/dot/nix/nixos && nix flake update && sudo nixos-rebuild switch --flake .#nix --impure'
alias nixos-rebuild-switch='sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure'
```

## Rollback Plan

If anything goes wrong, you can always rollback:

```bash
# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

# Or select from boot menu
# Reboot and choose previous generation
```

Your old channel-based config is still at `/etc/nixos/configuration.nix.backup`.

## Common Commands

### With Flakes

```bash
# Update all inputs (nixpkgs, home-manager, nixos-wsl)
nix flake update

# Update just one input
nix flake lock --update-input nixpkgs

# Apply configuration
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

# Test without applying
sudo nixos-rebuild build --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

# Check what changed
nix flake metadata /home/pan/dev/config/dot/nix/nixos
git diff flake.lock  # See version changes
```

### Garbage Collection

```bash
# Delete old generations (save disk space)
sudo nix-collect-garbage --delete-older-than 30d

# Full cleanup
sudo nix-collect-garbage -d
sudo nix-store --optimise
```

## FAQ

### Do I need to remove channels?

No, but you can clean them up:
```bash
sudo nix-channel --list  # See current channels
sudo nix-channel --remove nixos  # Remove if desired
```

### Will my existing packages break?

No! The flake uses the same package set (nixos-unstable). Your home-manager config stays the same.

### What about `--impure` flag?

You need it because `home.nix` uses `NIX_LD` which reads from the store at evaluation time. This is fine and expected for this use case.

### Can I still use `nixos-rebuild switch` without flags?

Not directly with flakes. But you can:
1. Create an alias (see Step 5)
2. Symlink to `/etc/nixos/flake.nix` and use `--flake /etc/nixos#nix`

### How do I update packages now?

```bash
# Update flake.lock to latest versions
nix flake update

# Then rebuild
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure
```

## Benefits You'll Get

1. **Exact versions**: `flake.lock` pins everything
2. **Faster updates**: Only download what changed
3. **Better caching**: Flakes have better binary cache hits
4. **Git-friendly**: Your whole system in version control
5. **Easy sharing**: Others can reproduce your exact system

## Next Steps After Migration

1. ✅ Commit your configuration to git
2. ✅ Remove old channels (optional)
3. ✅ Set up shell aliases
4. ✅ Enjoy reproducible configs! 🎉