From c81e3341f1fea0b31931425944ff0d46919a0ec2 Mon Sep 17 00:00:00 2001 From: user3301 <26126682+user3301@users.noreply.github.com> Date: Mon, 21 Sep 2026 12:39:00 +1000 Subject: [PATCH] Remove macOS and Arch Nix configs and refresh documentation Use Homebrew Bundle and GNU Stow on macOS, and the pacman package list with Stow on Arch Linux. Preserve NixOS configurations and align setup and documentation with the platform split. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Brewfile | 1 + Makefile | 102 +--- README | 50 +- docs/ARCHITECTURE.md | 607 +++++----------------- docs/DEPLOYMENT.md | 560 ++++++-------------- docs/EXAMPLE-VERSION-PINNING.md | 305 +++-------- docs/IMPLEMENTATION_SUMMARY.md | 507 ++---------------- docs/QUICK_REFERENCE.md | 528 +++---------------- docs/README.nix.md | 404 ++++---------- flake.lock | 21 - flake.nix | 102 +--- git/.config/git/README.md | 75 +-- home/archlinux.nix | 40 -- home/darwin.nix | 39 -- home/modules/common.nix | 2 +- home/modules/wezterm.nix | 2 +- nvim/.config/nvim/README.md | 57 +- nvim/.config/nvim/lua/plugins/conform.lua | 2 +- systems/darwin/configuration.nix | 78 --- systems/native/configuration.nix | 4 +- systems/wsl/configuration.nix | 2 +- 21 files changed, 738 insertions(+), 2750 deletions(-) delete mode 100644 home/archlinux.nix delete mode 100644 home/darwin.nix delete mode 100644 systems/darwin/configuration.nix diff --git a/Brewfile b/Brewfile index 9cf0a03..071c6ab 100644 --- a/Brewfile +++ b/Brewfile @@ -1,3 +1,4 @@ +brew 'stow' brew 'git-delta' brew 'herdr' cask 'wezterm' diff --git a/Makefile b/Makefile index 5e45a22..6202a96 100644 --- a/Makefile +++ b/Makefile @@ -1,84 +1,40 @@ .DEFAULT_GOAL := help +STOW_PACKAGES ?= bash fastfetch git herdr lazygit nvim wezterm yazi zsh + .PHONY: help help: @echo "Dotfiles Setup Commands:" @echo "" @echo "Initial Setup:" - @echo " make install-nix - Install Nix package manager" - @echo " make setup-home-manager - Bootstrap home-manager (first time setup)" - @echo " make setup-mac - Full setup for macOS (Nix + home-manager + Homebrew)" - @echo " make setup-linux - Full setup for Linux (Nix + home-manager)" - @echo " make setup-wsl-nixos - Link NixOS configuration for WSL2 (requires sudo)" + @echo " make setup-mac - Install Brewfile packages and Stow dotfiles + AeroSpace" + @echo " make setup-arch - Install pacman list and Stow dotfiles" + @echo " make stow - Symlink STOW_PACKAGES into your home directory" + @echo " make setup-wsl-nixos - Stage NixOS WSL2 from an existing checkout (sudo)" @echo "" @echo "NixOS WSL2 Commands:" @echo " make switch - Rebuild NixOS system (slow, needs sudo)" - @echo " make home-switch - Rebuild home-manager only (fast, no sudo)" @echo " make build - Build system without switching (test config)" @echo " make update - Update flake inputs" @echo " make upgrade - Update flake inputs and rebuild" @echo " make generations - List system generations" - @echo " make home-generations - List home-manager generations" @echo " make gc - Run garbage collection" @echo " make clean - Deep clean (delete old generations + gc)" @echo "" @echo "Other Commands:" @echo " make set-default-shell - Set zsh as default shell (requires sudo)" @echo " make install-brew - Install Homebrew (macOS only)" - @echo " make install-brew-packages- Install GUI apps via Homebrew (macOS only)" + @echo " make install-brew-packages - Install packages from Brewfile (macOS only)" + @echo " make install-arch-packages - Upgrade Arch and install pacman-packages.txt" @echo "" -.PHONY: install-nix -install-nix: - @echo "Installing Nix package manager..." - curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install - -.PHONY: setup-home-manager -setup-home-manager: - @echo "Activating home-manager configuration..." - @echo "Detecting system..." - @if [ "$$(uname -s)" = "Darwin" ]; then \ - if [ "$$(uname -m)" = "arm64" ]; then \ - echo "Detected: macOS Apple Silicon"; \ - nix run nix-darwin -- switch --flake .#aarch64; \ - else \ - echo "Detected: macOS Intel"; \ - nix run nix-darwin -- switch --flake .#x86_64; \ - fi \ - else \ - if [ "$$(uname -m)" = "x86_64" ]; then \ - echo "Detected: Linux x86_64"; \ - nix run home-manager/master -- switch --flake .#$$USER-x86_64-linux; \ - else \ - echo "Detected: Linux ARM64"; \ - nix run home-manager/master -- switch --flake .#$$USER-aarch64-linux; \ - fi \ - fi - -.PHONY: update-home-manager -update-home-manager: - @echo "Updating home-manager configuration..." - @if [ "$$(uname -s)" = "Darwin" ]; then \ - if [ "$$(uname -m)" = "arm64" ]; then \ - darwin-rebuild switch --flake .#aarch64; \ - else \ - darwin-rebuild switch --flake .#x86_64; \ - fi \ - else \ - if [ "$$(uname -m)" = "x86_64" ]; then \ - nix run home-manager/master -- switch --flake .#$$USER-x86_64-linux; \ - else \ - nix run home-manager/master -- switch --flake .#$$USER-aarch64-linux; \ - fi \ - fi - .PHONY: set-default-shell set-default-shell: @echo "Setting zsh as default shell..." @echo "This requires sudo access to modify /etc/shells" @ZSH_PATH=$$(which zsh); \ if [ -z "$$ZSH_PATH" ]; then \ - echo "Error: zsh not found. Run 'make setup-home-manager' first."; \ + echo "Error: zsh not found. Install it with your OS package manager first."; \ exit 1; \ fi; \ echo "Found zsh at: $$ZSH_PATH"; \ @@ -102,19 +58,26 @@ install-brew: .PHONY: install-brew-packages install-brew-packages: @echo "Installing Homebrew packages..." - brew bundle + brew bundle --file=Brewfile + +.PHONY: install-arch-packages +install-arch-packages: + @echo "Upgrading Arch Linux and installing packages..." + sudo pacman -Syu --needed - < pacman-packages.txt + +.PHONY: stow +stow: + stow --dir="$(CURDIR)" --target="$(HOME)" $(STOW_PACKAGES) .PHONY: setup-mac -setup-mac: install-nix setup-home-manager install-brew install-brew-packages - @echo "" - @echo "✅ macOS setup complete!" - @echo "Packages installed via Nix, GUI apps installed via Homebrew" +setup-mac: install-brew-packages + $(MAKE) stow STOW_PACKAGES="$(STOW_PACKAGES) aerospace" + @echo "Brewfile packages installed and macOS dotfiles linked." -.PHONY: setup-linux -setup-linux: install-nix setup-home-manager - @echo "" - @echo "✅ Linux setup complete!" - @echo "All packages and configs installed via Nix" +.PHONY: setup-arch +setup-arch: install-arch-packages + $(MAKE) stow + @echo "Pacman packages installed and Arch Linux dotfiles linked." .PHONY: setup-wsl-nixos setup-wsl-nixos: @@ -142,11 +105,6 @@ switch: @echo "Rebuilding NixOS system..." sudo nixos-rebuild switch --flake .#nixos-wsl -.PHONY: home-switch -home-switch: - @echo "Rebuilding home-manager configuration..." - nix run home-manager/master -- switch --flake .#nixos-wsl - .PHONY: build build: @echo "Building NixOS system (without switching)..." @@ -166,11 +124,6 @@ generations: @echo "System generations:" sudo nix-env --list-generations --profile /nix/var/nix/profiles/system -.PHONY: home-generations -home-generations: - @echo "Home-manager generations:" - nix run home-manager/master -- generations - .PHONY: gc gc: @echo "Running garbage collection..." @@ -182,7 +135,4 @@ clean: @echo "Deep cleaning old generations and running garbage collection..." @echo "Deleting system generations older than 7 days..." sudo nix-collect-garbage --delete-older-than 7d - @echo "Deleting home-manager generations older than 7 days..." - nix run home-manager/master -- expire-generations "-7 days" @echo "✅ Deep clean complete!" - diff --git a/README b/README index c3ec2cb..0e672f2 100644 --- a/README +++ b/README @@ -1,12 +1,48 @@ -Fully Reproducible dotfiles config +Dotfiles +======== -"Dotfiles managed by Nix: because spending 40 hours to save 4 minutes is a lifestyle. Fully reproducible - I've tested it on my Windows gaming rig (NixOS-WSL2), my wife's MacBook Air, and my own laptop (I use Arch BTW). If it works there, it'll work anywhere." +Shared application configuration with platform-specific package management: -Follows the XDG Base Directory Specification - keeping your home directory clean and uncluttered by organizing all configuration files in ~/.config instead of scattering dotfiles everywhere. + NixOS WSL2 / native NixOS Nix flakes + integrated Home Manager + macOS Homebrew Bundle (Brewfile) + GNU Stow + Arch Linux pacman (pacman-packages.txt) + GNU Stow -For Nix setup and usage, see docs/README.nix.md. +Nix is only used for NixOS. There are no macOS or standalone Linux Home +Manager configurations. The native package lists are smaller than the NixOS +development environment; they do not install every configured application. -FAQ +Most application configs live under .config in Stow-compatible directories. +Zsh and Bash startup files live directly in the home directory. Symlinks keep +the checkout editable; application config changes take effect after reloading +the application, without a Nix rebuild. -Q: Why Nix? -A: Because I like pain and reproducibility. +Getting started +--------------- + +Read docs/DEPLOYMENT.md first for prerequisites, shell dependencies, existing +file conflicts, and native NixOS hardware customization. + +From a checkout at ~/dotfiles: + + macOS: make setup-mac (requires Homebrew on PATH) + Arch Linux: make setup-arch (requires sudo and pacman) + +For a fresh, already installed NixOS-WSL distribution: + + nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl + +For ongoing NixOS WSL updates: make switch +For native NixOS: sudo nixos-rebuild switch --flake .#nixos-native +Both NixOS configurations use /home/user3301/dotfiles. + +Documentation +------------- + + docs/DEPLOYMENT.md Installation, migration, and local settings + docs/QUICK_REFERENCE.md Common commands + docs/ARCHITECTURE.md Source layout, modules, and CI + docs/README.nix.md NixOS usage and maintenance + docs/EXAMPLE-VERSION-PINNING.md The Nix package pins used by this repo + docs/IMPLEMENTATION_SUMMARY.md Current platform support and boundaries + git/.config/git/README.md Git identity and SSH commit signing + nvim/.config/nvim/README.md LazyVim and language-server setup diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2a33e1c..8b5c579 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,481 +1,130 @@ # Dotfiles Architecture -## Design Philosophy - -This dotfiles repository is designed with the following principles: - -1. **Reproducibility**: Identical environments across different machines and platforms -2. **Modularity**: Shared code between platforms, platform-specific overrides where needed -3. **Flexibility**: Support both NixOS (system-level) and non-NixOS (user-level) configurations -4. **Compatibility**: Preserve existing GNU Stow-compatible structure -5. **Separation of Concerns**: System configuration vs. user configuration - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────┐ -│ flake.nix │ -│ (Entry point, defines all outputs) │ -└─────────────────────────────────────────────────────────────┘ - │ - ┌───────────────────┼───────────────────┐ - │ │ │ - ▼ ▼ ▼ -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ NixOS │ │ Standalone │ │ nix-darwin │ -│ Configuration│ │ Home │ │ (macOS) │ -│ │ │ Manager │ │ │ -└──────────────┘ └──────────────┘ └──────────────┘ - │ │ │ - ▼ ▼ ▼ -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ system cfg + │ │ home cfg │ │ system cfg + │ -│ home cfg │ │ only │ │ home cfg │ -└──────────────┘ └──────────────┘ └──────────────┘ - │ │ │ - └───────────────────┼───────────────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Home Manager │ - │ Modules (Shared) │ - │ │ - │ • common.nix │ - │ • shell.nix │ - │ • dev-tools.nix │ - │ • neovim.nix │ - │ • terminal.nix │ - └───────────────────────┘ - │ - ▼ - ┌───────────────────────┐ - │ Existing Dotfiles │ - │ (Symlinked) │ - │ │ - │ • nvim/.config/nvim │ - │ • herdr/.config/... │ - │ • wezterm/.config/... │ - │ • etc. │ - └───────────────────────┘ -``` - -## Layer Breakdown - -### Layer 1: Flake Entry Point - -**File**: `/Users/gaiz/dotfiles/flake.nix` - -- Defines all inputs (nixpkgs, home-manager, nixos-wsl, nix-darwin) -- Provides outputs for different configurations -- Contains helper functions (`mkSystem`, `mkHome`, `mkDarwin`) - -**Outputs**: -- `nixosConfigurations.nixos-wsl`: WSL2 system + home config -- `nixosConfigurations.nixos-native`: Native NixOS system + home config -- `homeConfigurations.user@linux`: Standalone home config for Archlinux -- `darwinConfigurations.aarch64`: macOS system + home config - -### Layer 2: System Configurations - -**Purpose**: System-level settings (only on NixOS and macOS) - -**Files**: -- `systems/wsl/configuration.nix`: WSL2-specific system config -- `systems/native/configuration.nix`: Native NixOS system config -- `systems/darwin/configuration.nix`: macOS system config (via nix-darwin) - -**Responsibilities**: -- Boot configuration (native NixOS only) -- User account creation -- System packages (minimal) -- System services (SSH, networking, etc.) -- Platform-specific settings (WSL interop, macOS defaults, etc.) - -**Key Decision**: Keep system packages minimal. Most packages go in Home Manager. - -### Layer 3: Home Manager Configurations - -**Purpose**: User-level settings and packages - -**Files**: -- `home/nixos-wsl.nix`: WSL2 user config -- `home/nixos-native.nix`: Native NixOS user config -- `home/archlinux.nix`: Archlinux user config -- `home/darwin.nix`: macOS user config - -**Responsibilities**: -- Import shared modules -- Set username and home directory -- Platform-specific packages -- Platform-specific overrides -- Git user configuration - -### Layer 4: Shared Modules - -**Purpose**: Reusable configuration modules - -**Files** in `home/modules/`: - -1. **common.nix**: Base configuration - - Home Manager self-management - - XDG directory structure - - State version - - Unfree packages allowance - - Common environment variables - - Minimal base packages - -2. **shell.nix**: Shell configuration - - Zsh with plugins - - Sources existing .zshrc and .zshenv - - Bash fallback - -3. **dev-tools.nix**: Development packages - - Git, gh, lazygit - - Modern CLI tools (ripgrep, fd, bat, etc.) - - Build tools - - Nix development tools - -4. **neovim.nix**: Neovim configuration - - Enables neovim as default editor - - Installs LSP servers and formatters - - Symlinks existing nvim config - -5. **terminal.nix**: Terminal multiplexers and emulators - - Herdr configuration - - Wezterm configuration - - Yazi file manager - - Symlinks to existing configs - -**Design Pattern**: Each module is self-contained and can be independently enabled/disabled by commenting out the import. - -### Layer 5: Existing Dotfiles - -**Purpose**: Actual application configurations - -**Structure**: -``` -app-name/ - .config/ - app-name/ - config-files -``` - -This structure is compatible with GNU Stow and is symlinked by Home Manager using `mkOutOfStoreSymlink`. - -**Why symlink instead of copy?** -- Allows editing configs directly without rebuilding -- Keeps configs in familiar locations -- Maintains git history in dotfiles repo -- Compatible with manual management if needed - -## Configuration Flow - -### NixOS WSL2 Deployment - -``` -1. User runs: sudo nixos-rebuild switch --flake .#nixos-wsl - │ -2. Nix evaluates flake.nix ─────────────────┘ - │ -3. Loads nixosConfigurations.nixos-wsl - │ -4. Applies systems/wsl/configuration.nix - - Creates user3301 - - Configures WSL settings - - Enables zsh - │ -5. Loads Home Manager module (integrated) - │ -6. Evaluates home/nixos-wsl.nix - - Sets username/home directory - - Imports shared modules - │ -7. Each module does its job - - Installs packages - - Configures programs - - Creates symlinks to existing dotfiles - │ -8. System is now configured! -``` - -### Archlinux Deployment - -``` -1. User runs: home-manager switch --flake .#user@linux - │ -2. Nix evaluates flake.nix ───────────────┘ - │ -3. Loads homeConfigurations.user@linux - │ -4. Evaluates home/archlinux.nix - - Sets username/home directory - - Enables genericLinux target - - Imports shared modules - │ -5. Each module does its job - - Installs packages (to Nix profile) - - Configures programs - - Creates symlinks to existing dotfiles - │ -6. User environment is now configured! - (System packages still managed by pacman) -``` - -## Key Architectural Decisions - -### 1. Why separate system and home configurations? - -**Reason**: Enables both full NixOS systems and non-NixOS systems (Archlinux) to share the same user-level configuration. - -**Trade-off**: Slightly more complex structure, but much more flexible. - -### 2. Why use mkOutOfStoreSymlink? - -**Reason**: Allows editing dotfiles directly without Nix rebuilds. Configs remain in version control and can be modified interactively. - -**Alternative**: Use `home.file."path".source = ./path` to copy files into Nix store (immutable, requires rebuild to change). - -### 3. Why minimal system packages? - -**Reason**: -- Portability: Same packages work on NixOS and non-NixOS -- Rollback: Home Manager rollbacks are faster and don't affect system -- Separation: Clear boundary between system and user concerns - -**Exception**: System services and daemons should be in system config. - -### 4. Why not use nix-darwin for everything on macOS? - -**Reason**: Some macOS applications (especially GUI apps) are better managed via Homebrew due to notarization, automatic updates, and integration with macOS app store. - -**Hybrid approach**: -- nix-darwin for system settings and CLI tools -- Homebrew for GUI applications (Brewfile) -- Home Manager for user-level dotfiles - -### 5. Why flakes instead of channels? - -**Reason**: -- **Reproducibility**: Flakes pin exact versions (flake.lock) -- **Composability**: Easy to combine inputs -- **Portability**: Self-contained, no channel state -- **Modern**: Official Nix direction - -**Trade-off**: Requires Nix 2.4+ and experimental features enabled. - -## Module Interaction - -### Dependency Graph - -``` -common.nix (base, required) - │ - ├── shell.nix (depends on common for home.homeDirectory) - │ │ - │ └── Sources existing zsh configs - │ - ├── dev-tools.nix (standalone) - │ │ - │ └── Provides tools for other modules (gcc, etc.) - │ - ├── neovim.nix (depends on dev-tools for LSPs) - │ │ - │ └── Symlinks existing nvim config - │ - └── terminal.nix (standalone) - │ - └── Symlinks existing terminal configs -``` - -### Avoiding Circular Dependencies - -- **common.nix** has no dependencies -- **shell.nix** only reads from common -- Other modules can depend on common and dev-tools -- No module depends on terminal (it's a leaf node) - -### Override Mechanism - -Platform-specific configs can override any module setting: - -```nix -# In home/nixos-wsl.nix -imports = [ ./modules/common.nix ]; - -# Override a setting from common.nix -home.sessionVariables.EDITOR = "vim"; # Override from "nvim" -``` - -## Extension Points - -### Adding a New Platform - -1. Create system config (if NixOS-based): `systems/newplatform/configuration.nix` -2. Create home config: `home/newplatform.nix` -3. Add to `flake.nix` outputs -4. Update DEPLOYMENT.md - -### Adding a New Module - -1. Create `home/modules/newmodule.nix` -2. Import in relevant platform configs -3. Document in DEPLOYMENT.md - -### Adding Platform-Specific Packages - -Option 1: In platform's home config: -```nix -# home/nixos-wsl.nix -home.packages = with pkgs; [ wsl-specific-tool ]; -``` - -Option 2: Conditional in module: -```nix -# home/modules/dev-tools.nix -home.packages = with pkgs; [ - git -] ++ lib.optionals stdenv.isLinux [ - linux-specific-tool -]; -``` - -### Adding System Services (NixOS only) - -In system configuration: -```nix -# systems/native/configuration.nix -services.myservice = { - enable = true; - # configuration -}; -``` - -## Security Considerations - -### Secrets Management - -**Current approach**: Manual management for simplicity -- Git SSH keys are manually generated on each machine -- No automated secret management to reduce complexity -- Sensitive credentials kept outside of version control - -**Alternatives** (if needed in the future): -- **agenix**: Age-encrypted secrets -- **git-crypt**: Transparent git encryption -- **Local overrides**: `.zshenv.local` pattern (already in .gitignore) - -### Unfree Packages - -Currently enabled globally. To restrict: - -```nix -# In relevant config -nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (lib.getName pkg) [ - "vscode" - "slack" -]; -``` - -## Performance Optimizations - -### Build Caching - -- **Binary cache**: nixos.org enabled by default -- **Local cache**: Nix store auto-optimizes with hard links -- **Flake lock**: Prevents re-downloading unchanged inputs - -### Lazy Evaluation - -- Modules are only evaluated if imported -- Unused platform configs don't slow down builds -- Conditional package installation uses `lib.optionals` - -### Garbage Collection - -System configs enable automatic GC (weekly, 7-day retention). - -Manual GC: -```bash -# Delete generations older than 7 days -nix-collect-garbage --delete-older-than 7d - -# Delete all old generations -nix-collect-garbage -d -``` - -## Testing Strategy - -### Local Testing - -```bash -# Test without switching -sudo nixos-rebuild test --flake .#nixos-wsl - -# Build without activating -nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel - -# Check for errors -nix flake check -``` - -### CI/CD (Future) - -Consider GitHub Actions: -```yaml -- name: Check flake - run: nix flake check - -- name: Build all configs - run: | - nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel - nix build .#homeConfigurations.user@linux.activationPackage -``` - -## Migration Path - -### Phase 1: Minimal deployment (current) -- Basic system config -- Shared modules for dev tools -- Symlinks to existing dotfiles - -### Phase 2: Enhance modules -- Add more language-specific tools -- Configure more applications via Nix -- Add platform-specific optimizations - -### Phase 3: Advanced features -- Secrets management -- Custom NixOS modules -- Per-project development shells (flake.nix in projects) - -### Phase 4: Full declarative system -- All applications via Nix -- Automated backups -- Declarative VM configurations - -## Troubleshooting - -### Common Issues - -**Issue**: Symlinks conflict with existing files -**Solution**: Remove existing files or use `home.file."path".force = true` - -**Issue**: Module not found -**Solution**: Check import path is relative to file location - -**Issue**: Infinite recursion -**Solution**: Check for circular dependencies between modules - -**Issue**: Package not found -**Solution**: Search at search.nixos.org, ensure correct attribute path - -## Resources - -- **NixOS Manual**: https://nixos.org/manual/nixos/stable/ -- **Home Manager Manual**: https://nix-community.github.io/home-manager/ -- **Nix Pills**: https://nixos.org/guides/nix-pills/ -- **Discourse**: https://discourse.nixos.org/ - ---- - -This architecture balances **reproducibility**, **flexibility**, and **pragmatism**. It allows you to maintain your existing workflow while gaining the benefits of declarative configuration management. +## Platform boundaries + +Application configuration is shared; package management is not. + +```text +NixOS WSL2 / native macOS / Arch Linux + flake.nix Brewfile / pacman-packages.txt + systems/ + home/ native package installation + Home Manager symlinks GNU Stow symlinks + \ / + shared application files +``` + +Only NixOS uses the Nix modules. macOS uses Homebrew Bundle and Stow; Arch Linux +uses pacman and Stow. Neither native package manifest promises the same package +set or exact versions as NixOS. + +## Repository layout + +| Path | Responsibility | +| --- | --- | +| `flake.nix`, `flake.lock` | NixOS outputs, pinned inputs, overlays, checks, development shells | +| `systems/wsl/configuration.nix` | WSL user, interoperability, Docker, nix-ld, system settings | +| `systems/native/configuration.nix` | Native boot, networking, X11/Qtile/LightDM, SSH | +| `systems/hardware/hardware-vb.nix` | Currently imported VirtualBox hardware and filesystem config | +| `home/nixos-wsl.nix`, `home/nixos-native.nix` | User identity, module imports, platform packages | +| `home/modules/` | Shared NixOS user packages and links | +| `scripts/bootstrap-nixos-wsl.sh` | One-time NixOS-WSL bootstrap app | +| `Brewfile`, `pacman-packages.txt` | Native macOS and Arch package lists | +| `Makefile` | Native package/Stow helpers and NixOS WSL maintenance commands | +| `.github/workflows/ci.yml` | Quality checks and WSL evaluation | +| Application directories | Stow-compatible, editable configuration | + +Stow packages are `aerospace`, `bash`, `fastfetch`, `git`, `herdr`, `lazygit`, +`nvim`, `vim`, `wezterm`, `yazi`, and `zsh`. Most use +`/.config//`; Bash and Zsh contain home-directory startup +files. AeroSpace is macOS-only. Vim's XDG config requires explicit loading on +Vim versions that do not discover it. + +## Nix flake + +The inputs are `nixpkgs` (NixOS 26.05), `home-manager` (release-26.05), +`nixos-wsl`, `claude-code-nix`, `herdr`, and a commit-pinned +`nixpkgs-azure-cli`. `flake.lock` records the resolved revisions. + +`mkSystem` adds the Claude Code, Copilot CLI, and Azure CLI overlays to each +NixOS configuration. Home Manager uses `useGlobalPkgs = true`, so it receives +those same overlaid packages; `useUserPackages = true` installs home packages +through the NixOS user profile. The flake passes `inputs` to both module layers. +See [version pinning](EXAMPLE-VERSION-PINNING.md) for the package exceptions. + +| Output | Scope | +| --- | --- | +| `nixosConfigurations.nixos-wsl` | x86_64 WSL system and home | +| `nixosConfigurations.nixos-wsl-bootstrap` | Same WSL configuration plus activation-time checkout creation | +| `nixosConfigurations.nixos-native` | x86_64 native system and home | +| `packages.x86_64-linux.bootstrap-wsl` | Packaged bootstrap shell script | +| `apps.x86_64-linux.bootstrap-wsl` | Runnable bootstrap entry point | +| `checks.` | Nix quality, Lua format, Zsh syntax, Bash syntax | +| `formatter.` | nixfmt | +| `devShells..default` | Repository editing and lint tools | + +The checks, formatter, and development shell support `x86_64-linux` and +`aarch64-linux`. There is no ARM NixOS host output, no standalone Home Manager +output, and no Darwin output. + +The bootstrap activation creates `/home/user3301/dotfiles` if absent, using a +Git clone owned by `user3301`. Both normal NixOS homes require that mutable +checkout; the native output does not create it. + +## Home Manager modules + +| Module | What it manages | +| --- | --- | +| `common.nix` | XDG, Home Manager CLI, editor/DOTFILES session variables, archive/download tools | +| `shell.nix` | Oh My Zsh, Bash completion, McFly, zoxide, Bash/Zsh startup symlinks | +| `dev-tools.nix` | CLI/build tools, Kubernetes/Azure tools, Nix tools, Claude Code, Copilot CLI, devcontainer | +| `git.nix` | Git, gh, Lazygit, delta, GPG agent, Git/Lazygit symlinks, gh SSH protocol | +| `neovim.nix` | Neovim, language servers, formatters, Tree-sitter tools, fswatch, Neovim symlink | +| `terminal.nix` | Herdr, Yazi and its integration settings, Herdr/Yazi/Fastfetch symlinks | +| `wezterm.nix` | WezTerm symlink; imported only by the native home | +| `languages.nix` | Go, Rust, .NET 8, Protobuf, Python, Node.js toolchains | + +The WSL home adds PowerShell and sets `systemd.user.startServices = "suggest"` +so activation does not try to start user services before a normal WSL login. +The native home adds GnuPG, WezTerm, and Firefox. NixOS enables Zsh system-wide; +the shell module links the hand-written startup files rather than generating +them with Home Manager's shell programs. + +## Mutable configuration and reproducibility + +Home Manager uses `mkOutOfStoreSymlink` to link application directories or +startup files into `/home/user3301/dotfiles`. Stow links the same files on macOS +and Arch Linux. Editing a linked file changes the checkout immediately; reload +the application to pick it up. Adding a Nix module, package, or link requires a +NixOS rebuild; adding Stow-managed paths may require rerunning Stow. + +Nix pins package sources, not the live contents of these symlinked files. +System rollback does not roll back mutable dotfiles. Neovim plugins have their +own `lazy-lock.json` and are downloaded by lazy.nvim, not provisioned by the +Nix flake. Herdr plugins and credentials are also managed separately. + +Git identity/signing overrides and local shell settings are ignored by Git. +Herdr can write runtime state into its symlinked config directory; `.gitignore` +excludes those files. See [deployment](DEPLOYMENT.md#local-settings-and-manual-steps). + +## Existing CI + +`.github/workflows/ci.yml` runs on pushes to `master`, pull requests, and manual +dispatch. On Ubuntu it lints GitHub Actions, installs Nix, enables a binary +cache, builds the four `x86_64-linux` checks, and evaluates the WSL system +derivation: + +```sh +nix build --no-link \ + .#checks.x86_64-linux.nix-quality \ + .#checks.x86_64-linux.lua-format \ + .#checks.x86_64-linux.zsh-syntax \ + .#checks.x86_64-linux.bash-syntax +nix eval --raw '.#nixosConfigurations.nixos-wsl.config.system.build.toplevel.drvPath' +``` + +Nix quality runs nixfmt, statix, and deadnix on Nix files. Lua formatting uses +StyLua for Neovim and WezTerm. Shell checks parse the Bash and Zsh startup +files. CI does not build full NixOS systems, evaluate the native host, install +Homebrew/pacman packages, or activate Stow links. + +`nix develop` provides deadnix, Git, nil, nixfmt, statix, StyLua, Vim, and Zsh. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 6af90d4..2ff5ae7 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -1,468 +1,250 @@ -# Deployment Guide for Cross-Platform Dotfiles +# Deployment Guide -This repository provides reproducible configurations for: -- **NixOS WSL2** (Windows Subsystem for Linux) -- **NixOS Native** (bare metal or VM) -- **Archlinux** with Nix + Home Manager -- **macOS** with nix-darwin (current setup) +| Platform | Packages | Dotfiles | +| --- | --- | --- | +| macOS | Homebrew Bundle using the root `Brewfile` | GNU Stow | +| Arch Linux | pacman using the root `pacman-packages.txt` | GNU Stow | +| NixOS WSL2 | Nix flake, `nixos-wsl` | Integrated Home Manager | +| Native NixOS | Nix flake, `nixos-native` | Integrated Home Manager | -## Directory Structure +Nix is not required or configured for macOS or Arch Linux. The native package +lists do not mirror the larger NixOS package set. -``` -dotfiles/ -├── flake.nix # Main flake configuration -├── home/ # Home Manager configurations -│ ├── modules/ # Shared modules -│ │ ├── common.nix # Common settings -│ │ ├── shell.nix # Shell configuration -│ │ ├── dev-tools.nix # Development tools -│ │ ├── neovim.nix # Neovim configuration -│ │ └── terminal.nix # Terminal multiplexers & emulators -│ ├── nixos-wsl.nix # WSL2-specific home config -│ ├── nixos-native.nix # Native NixOS home config -│ ├── archlinux.nix # Archlinux home config -│ └── darwin.nix # macOS home config -├── systems/ # NixOS system configurations -│ ├── wsl/ -│ │ └── configuration.nix # WSL2 system config -│ ├── native/ -│ │ └── configuration.nix # Native NixOS system config -│ └── darwin/ -│ └── configuration.nix # macOS system config -└── [app-configs]/ # Existing dotfiles (nvim, herdr, wezterm, etc.) -``` - -## Prerequisites - -All platforms need Nix with flakes enabled. Choose your platform: - -### For NixOS (WSL2 or Native) -Nix is already installed. Ensure flakes are enabled in `/etc/nixos/configuration.nix`: -```nix -nix.settings.experimental-features = [ "nix-command" "flakes" ]; -``` - -### For Archlinux or other Linux distributions -```bash -# Install Nix using Determinate Systems installer (recommended) -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install - -# Or use official installer -sh <(curl -L https://nixos.org/nix/install) --daemon -``` - -### For macOS -```bash -# Install Nix (if not already installed) -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install -``` - -## Bootstrap Process (First-Time Setup on Clean NixOS) +## Before installing -**The Chicken-and-Egg Problem**: On a fresh NixOS installation (WSL2 or Native), git is not installed by default, but you need git to clone the dotfiles repository. Here's how to solve this: +Review the configuration before using it on another machine. Back up individual +files that would conflict with symlinks; neither Stow nor Home Manager should +overwrite your existing configuration. Do not use `stow --adopt` unless you +intend to move existing files into this repository. -### Option 1: Using nix-shell (Traditional Method) +Keep the checkout at `~/dotfiles`. NixOS explicitly expects +`/home/user3301/dotfiles`, and the Zsh local override also uses `~/dotfiles`. +Do not run Stow on paths already managed by Home Manager. -```bash -# Enter a temporary shell with git -nix-shell -p git +For macOS and Arch Linux, start with Git installed and clone the repository: -# Clone the dotfiles repo (while in nix-shell) +```sh git clone https://github.com/user3301/dotfiles.git ~/dotfiles cd ~/dotfiles - -# Link the NixOS configuration and build -make setup-wsl-nixos # for WSL2 (stages config for next boot) - -# Exit the temporary shell -exit - -# Then restart WSL (in PowerShell): wsl --shutdown -# Reopen NixOS and run: cd ~/dotfiles && make switch - -# Now git is permanently installed as part of your system! ``` -### Option 2: Using nix run (Modern Method) - -```bash -# Clone using temporary git (no shell needed) -nix run nixpkgs#git -- clone https://github.com/user3301/dotfiles.git ~/dotfiles -cd ~/dotfiles - -# Link the NixOS configuration and build -make setup-wsl-nixos # for WSL2 (stages config for next boot) +On macOS, Apple's Command Line Tools provide Git and Make; install them with +`xcode-select --install` if needed. On Arch Linux, install Git first with +`sudo pacman -Syu --needed git`. If Make is not yet available, use the direct +package installation commands below; the Arch list includes `base-devel`. -# Then restart WSL (in PowerShell): wsl --shutdown -# Reopen NixOS and run: cd ~/dotfiles && make switch -``` +## macOS -**After the first deployment**, git is permanently installed as part of `environment.systemPackages`, so you can use it normally for updates: +Install [Homebrew](https://brew.sh/) if necessary (`make install-brew` runs its +installer). Follow the installer's shell setup instructions so `brew` is on +`PATH`; the prefix differs between Apple Silicon and Intel. -```bash +```sh cd ~/dotfiles -git pull -make switch +brew bundle --file=Brewfile ``` ---- - -## Deployment Instructions - -After the first Nix build on a new machine, manually install the Herdr plugins [Auto Title](https://github.com/kryptamine/herdr-auto-title) and [reviewr](https://github.com/persiyanov/herdr-reviewr). These two plugins are not managed by Nix. - -### 1. NixOS WSL2 +The Brewfile installs GNU Stow, git-delta, Herdr, WezTerm, and AeroSpace. It does +not install the full NixOS toolchain or manage macOS system preferences. -**First-time setup on clean WSL2:** +Before enabling the Zsh configuration, read [Shell and application +dependencies](#shell-and-application-dependencies). Then preview and create links: -```bash -# Step 1: Get temporary git access (choose one method from Bootstrap Process above) -nix-shell -p git - -# Step 2: Clone the dotfiles repo -git clone https://github.com/user3301/dotfiles.git ~/dotfiles -cd ~/dotfiles - -# Step 3: Link config, build, and stage the system for next boot -make setup-wsl-nixos - -# Step 4: Exit temporary shell and restart WSL -exit -``` - -Then in **PowerShell / Windows Terminal**: -```powershell -wsl --shutdown +```sh +stow --simulate --verbose --target="$HOME" \ + bash fastfetch git herdr lazygit nvim wezterm yazi zsh aerospace +stow --target="$HOME" \ + bash fastfetch git herdr lazygit nvim wezterm yazi zsh aerospace ``` -Reopen your NixOS WSL2 distro: -```bash -# Step 5: Verify the configuration is active -cd ~/dotfiles -make switch -``` +`make setup-mac` runs the Brewfile installation and Stow steps in order. It +requires Homebrew to be installed already and does not change your login shell. +On later updates, rerun `brew bundle --file=Brewfile` for manifest changes and +Stow when adding config files or packages. -> **Why `boot` then restart?** NixOS 25.05+ changed the default D-Bus -> implementation from `dbus` to `dbus-broker`. A live `switch` on a fresh -> install triggers a switch inhibitor for this critical component change. -> Using `boot` stages the config cleanly, and the WSL restart activates it. +## Arch Linux -The system will have: -- Configured WSL2 settings -- Created user `user3301` -- Installed Home Manager packages -- Symlinked all dotfiles -- Permanently installed git and other system packages +Install the root package list using a full system upgrade, avoiding partial +upgrades: -**Subsequent updates:** -```bash +```sh cd ~/dotfiles -make switch +sudo pacman -Syu --needed - < pacman-packages.txt ``` -**Important Notes for WSL2:** -- Username is `user3301` (configured in `systems/wsl/configuration.nix`) -- Default shell is zsh -- WSL interoperability is enabled by default -- Windows paths are accessible via `/mnt/c/...` - -### 2. NixOS Native - -**First-time setup on clean NixOS:** - -```bash -# Step 1: Get temporary git access (see Bootstrap Process above) -nix-shell -p git - -# Step 2: Clone the dotfiles repo -git clone https://github.com/user3301/dotfiles.git ~/dotfiles -cd ~/dotfiles - -# Step 3: IMPORTANT - Generate hardware configuration first -sudo nixos-generate-config --show-hardware-config > ~/dotfiles/systems/native/hardware-configuration.nix - -# Step 4: Edit systems/native/configuration.nix to uncomment the hardware import: -# imports = [ ./hardware-configuration.nix ]; - -# Step 5: Customize your setup in systems/native/configuration.nix: -# - Choose display manager, desktop environment -# - Configure graphics drivers -# - Set hostname, timezone, locale - -# Step 6: Deploy the system configuration -sudo nixos-rebuild switch --flake .#nixos-native +The list includes Git, OpenSSH, Stow, Zsh, eza, Lazygit, fd, ripgrep, GitHub CLI, +xclip, `base-devel`, sudo, and which. It does not include every configured +application: for example, Neovim and delta need to be installed separately if +you use the editor and Git configurations. -# Step 7: Exit temporary shell -exit -``` +After preparing the dependencies below, link the desired packages: -**Subsequent updates:** -```bash -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-native +```sh +stow --simulate --verbose --target="$HOME" \ + bash fastfetch git herdr lazygit nvim wezterm yazi zsh +stow --target="$HOME" \ + bash fastfetch git herdr lazygit nvim wezterm yazi zsh ``` -**Customization:** -Before deploying, edit `systems/native/configuration.nix` to: -- Choose display manager (lightdm, gdm, etc.) -- Choose desktop environment (GNOME, KDE, i3, etc.) -- Configure graphics drivers (NVIDIA, AMD, Intel) -- Set timezone and locale -- Configure networking hostname - -### 3. Archlinux with Nix + Home Manager - -**First-time setup:** +With Make available, `make setup-arch` installs the pacman list and then creates +these links. AeroSpace is macOS-only and is not included. -```bash -# 1. Install Nix (if not already done) -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +## Shell and application dependencies -# 2. Clone dotfiles -git clone https://github.com/yourusername/dotfiles.git ~/dotfiles -cd ~/dotfiles - -# 3. Edit home/archlinux.nix to set your actual username -# Change 'user3301' to your actual Arch username - -# 4. Deploy Home Manager configuration -nix run home-manager/master -- switch --flake .#user@linux +Stow only creates links; it does not install applications or their dependencies. +Add desired macOS packages to `Brewfile`, or Arch packages to +`pacman-packages.txt`, and rerun the corresponding install command. -# Note: Replace 'user@linux' with 'username@linux' if you changed the username -``` +The shared Zsh config unconditionally loads Oh My Zsh from `~/.oh-my-zsh`. +On macOS and Arch Linux, install it before opening a shell with this config. +If that directory does not already exist: -**Subsequent updates:** -```bash -cd ~/dotfiles -home-manager switch --flake .#user@linux +```sh +git clone https://github.com/ohmyzsh/ohmyzsh.git ~/.oh-my-zsh ``` -**Important Notes for Archlinux:** -- This is a **standalone Home Manager** setup (no NixOS) -- System packages should still be installed via `pacman` -- Nix manages development tools and user applications -- Username must match your actual Arch username -- Edit `home/archlinux.nix` to set correct username and home directory - -### 4. macOS (Current Setup) +Zsh uses the `pygmalion` theme and the Git, z, colored-man-pages, asdf, and vi-mode +plugins. Its `ls` aliases require eza. Both shells select `nvim` as the editor, +so install Neovim or adjust the editor setting. McFly is optional; Bash also +uses zoxide when installed. The asdf plugin/shim path does not install asdf or +any language runtimes. -**First-time setup:** +Git and Lazygit use delta. Configure your Git identity and signing key using +the [Git README](../git/.config/git/README.md). Language-server and formatter +dependencies are covered in the [Neovim README](../nvim/.config/nvim/README.md). +WezTerm's font configuration requests JetBrains Mono, Ubuntu Mono, and More +Perfect DOS VGA; install desired fonts separately on non-NixOS machines. -```bash -# Already set up via nix-darwin -# Use existing Makefile commands: -make setup-mac -``` +The default `make stow` selection is: +`bash fastfetch git herdr lazygit nvim wezterm yazi zsh`. +You can link a smaller subset: -**Subsequent updates:** -```bash -darwin-rebuild switch --flake .#aarch64 # For Apple Silicon -# or -darwin-rebuild switch --flake .#x86_64 # For Intel Macs +```sh +make stow STOW_PACKAGES="git nvim" ``` -## Configuration Customization +`make setup-mac` adds `aerospace` to that selection. `vim` is another Stow +package, but it is not linked by default: its file is `~/.config/vim/vimrc`. +If your Vim does not discover that path, load it explicitly with +`vim -u ~/.config/vim/vimrc` or source it from your own `~/.vimrc`. -### Changing Username or Email +After installing Zsh, `make set-default-shell` registers it in `/etc/shells` +if needed and calls `chsh`. Log out and back in afterward. -Edit the appropriate home configuration file: -- **WSL2**: `home/nixos-wsl.nix` -- **Native NixOS**: `home/nixos-native.nix` -- **Archlinux**: `home/archlinux.nix` -- **macOS**: `home/darwin.nix` +### Migrating an existing Nix-managed macOS or Arch home -```nix -programs.git = { - enable = true; - userName = "Your Name"; - userEmail = "your.email@example.com"; -}; -``` +Removing this repository's old Nix configuration does not uninstall Nix or +remove links from a previously activated generation. Back up local overrides, +install native replacements, and retire the previous Home Manager/nix-darwin +setup using the tooling that created it before Stowing the same paths. Check +existing links with `ls -l`; do not let Stow write through an old Nix-managed +directory. NixOS homes should continue using Home Manager instead. -### Adding New Packages +## NixOS WSL2 -**System-wide packages (NixOS only):** -Edit `systems/{wsl,native}/configuration.nix`: -```nix -environment.systemPackages = with pkgs; [ - vim - git - # Add your packages here -]; -``` +Start with an existing [NixOS-WSL](https://github.com/nix-community/NixOS-WSL) +distribution, not Ubuntu or another WSL distribution. From a user able to run +sudo: -**User packages (all platforms):** -Edit `home/modules/dev-tools.nix` or your platform-specific home config: -```nix -home.packages = with pkgs; [ - # Add your packages here - htop - docker -]; +```sh +nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl ``` -### Adding New Modules +The app in `scripts/bootstrap-nixos-wsl.sh` checks for WSL and `nixos-rebuild`, +then switches to `nixos-wsl-bootstrap`. That configuration creates `user3301` +and clones the repository to `/home/user3301/dotfiles` before Home Manager +activation. An existing Git checkout is left intact; an existing non-checkout +at that path is rejected. It can be rerun after an interrupted bootstrap. +`DOTFILES_FLAKE` overrides the rebuild's flake reference, not the clone URL. -Create a new module in `home/modules/` and import it in your platform configs: +From PowerShell, restart WSL: -```nix -# home/modules/mymodule.nix -{ config, pkgs, lib, ... }: -{ - # Your module configuration -} - -# Then import in home/nixos-wsl.nix (or other configs) -imports = [ - ./modules/common.nix - ./modules/mymodule.nix # Add this -]; +```powershell +wsl --shutdown ``` -## Updating Flake Inputs +Reopen as `user3301`, then use the normal output for subsequent changes: -```bash -# Update all inputs -nix flake update - -# Update specific input -nix flake lock --update-input nixpkgs - -# Then rebuild your system -sudo nixos-rebuild switch --flake .#nixos-wsl # or your config +```sh +cd ~/dotfiles +make switch ``` -## Troubleshooting - -### Symlinks not working on Archlinux +The WSL configuration enables Zsh, Docker, Windows interoperability, and +`nix-ld`; the SSH server is disabled. WezTerm is not installed or linked by this +home configuration: the terminal runs on the Windows host and must be configured +there separately. -On non-NixOS systems, Home Manager uses `mkOutOfStoreSymlink` which requires absolute paths. Ensure `config.home.homeDirectory` is set correctly in `home/archlinux.nix`. +For an existing checkout at the expected user path, `make setup-wsl-nixos` is +the alternate boot-staging workflow. It links the WSL system module into +`/etc/nixos/configuration.nix` and runs `nixos-rebuild boot --flake .#nixos-wsl`. +Restart WSL afterward. Continue using explicit `--flake` commands: that module +alone is not the full configuration. -### "conflicting files" error +## Native NixOS -Home Manager won't overwrite existing files. Either: -1. Backup and remove conflicting files: `mv ~/.config/nvim ~/.config/nvim.bak` -2. Or let Home Manager manage the files by using `home.file."path".force = true` +This is a configuration for an already installed x86_64 NixOS system, not a disk +installer. It currently imports `systems/hardware/hardware-vb.nix`, which +contains VirtualBox-specific modules and filesystem UUIDs. **Replace that +hardware import before deploying to another machine.** -### WSL2 specific issues +If Git is unavailable, obtain it temporarily with `nix-shell -p git`. Clone as +the intended user into `/home/user3301/dotfiles`, then: -**Permission denied on /etc/nixos:** -```bash -sudo mkdir -p /etc/nixos -sudo chown -R $USER:$USER /etc/nixos -``` - -**Windows paths not accessible:** -Ensure WSL interop is enabled in `systems/wsl/configuration.nix`: -```nix -wsl.interop.register = true; +```sh +cd ~/dotfiles +sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix ``` -### Flake evaluation errors - -```bash -# Check for syntax errors -nix flake check +Change the `imports` entry in `systems/native/configuration.nix` from +`../hardware/hardware-vb.nix` to `./hardware-configuration.nix`. Add the new file +to Git so the local Git-backed flake can see it: -# Show detailed evaluation -nix flake show --allow-import-from-derivation +```sh +git add systems/native/hardware-configuration.nix ``` -## Migration Strategy - -### From existing non-Nix setup - -1. **Backup existing configs**: - ```bash - mv ~/.config ~/.config.backup - ``` - -2. **Deploy minimal configuration first**: - Comment out modules in your home config and add them incrementally - -3. **Test each module**: - After adding each module, rebuild and verify it works - -4. **Keep both systems during transition**: - You can keep your old configs and gradually migrate - -### From NixOS without flakes - -1. **Enable flakes** in your current `/etc/nixos/configuration.nix`: - ```nix - nix.settings.experimental-features = [ "nix-command" "flakes" ]; - ``` - -2. **Rebuild to enable flakes**: - ```bash - sudo nixos-rebuild switch - ``` - -3. **Then switch to flake configuration**: - ```bash - cd ~/dotfiles - sudo nixos-rebuild switch --flake .#nixos-wsl - ``` +Review bootloader, user, hostname, networking, and graphics settings. The +current desktop uses X11, Qtile, and LightDM; NetworkManager and the SSH server +are enabled, with password and root SSH login disabled. -## Platform-Specific Notes - -### NixOS WSL2 -- **Pros**: Full NixOS experience, declarative system config -- **Cons**: WSL2 limitations (no systemd by default, handled by nixos-wsl) -- **Use case**: Development environment on Windows - -### NixOS Native -- **Pros**: Full system control, best Nix experience -- **Cons**: Learning curve, need to configure hardware -- **Use case**: Primary workstation, servers - -### Archlinux + Nix/Home Manager -- **Pros**: Best of both worlds (pacman + Nix), gradual adoption -- **Cons**: Two package managers, can't configure system via Nix -- **Use case**: Already on Arch, want reproducible user environment - -### macOS + nix-darwin -- **Pros**: Declarative package management on macOS -- **Cons**: Still need Homebrew for some GUI apps, macOS updates can break Nix -- **Use case**: Development on macOS - -## Advanced Usage - -### Testing configurations without switching - -```bash -# NixOS -sudo nixos-rebuild test --flake .#nixos-wsl - -# Home Manager -home-manager build --flake .#user@linux -./result/activate +```sh +sudo nixos-rebuild build --flake .#nixos-native +sudo nixos-rebuild switch --flake .#nixos-native ``` -### Building for different architecture +If flakes are not enabled yet, pass the setting to the rebuild explicitly: -```bash -# Build for ARM64 from x86_64 -nix build .#homeConfigurations.user@linux-arm64.activationPackage \ - --system aarch64-linux +```sh +sudo env NIX_CONFIG='experimental-features = nix-command flakes' \ + nixos-rebuild build --flake .#nixos-native ``` -### Using direnv (optional) +Use the same prefix for `switch`. The deployed configuration enables flakes +permanently. -Create `.envrc` in project directories: -```bash -use flake -``` +Both NixOS outputs hard-code `user3301`. To change it, update the system user, +the matching `home-manager.users` key in `flake.nix`, and `home.username` and +`home.homeDirectory` in the selected home module. WSL bootstrap additionally +hard-codes its user and clone location in the flake and bootstrap script. + +## Local settings and manual steps -Then `direnv allow` to auto-load Nix environments. +The following local overrides are already ignored by Git: -## Support +| File | Loaded by | +| --- | --- | +| `git/.config/git/config.local` | Shared Git config, after the defaults | +| `zsh/.zshenv.local` | `~/.zshenv`, from `~/dotfiles` | +| `bash/.bashrc.local` | Interactive Bash, from `$DOTFILES/bash` | -For issues or questions: -1. Check the NixOS Wiki: https://nixos.wiki/ -2. NixOS Discourse: https://discourse.nixos.org/ -3. Home Manager Manual: https://nix-community.github.io/home-manager/ +Do not commit credentials or private keys. There is no automated secrets +provisioning. ---- +Install Herdr's [Auto Title](https://github.com/kryptamine/herdr-auto-title) and +[reviewr](https://github.com/persiyanov/herdr-reviewr) plugins manually when using +Herdr. The tracked config binds `Alt+r` to reviewr; plugin state is ignored. +Herdr and Fastfetch auto-start snippets in `.zshrc` are commented out. -**Remember**: The beauty of this setup is reproducibility. Once configured, you can deploy identical environments across all your machines with a single command! +See [NixOS maintenance](README.nix.md) and the +[command reference](QUICK_REFERENCE.md) for updates and troubleshooting. diff --git a/docs/EXAMPLE-VERSION-PINNING.md b/docs/EXAMPLE-VERSION-PINNING.md index e4ce5ff..20da74c 100644 --- a/docs/EXAMPLE-VERSION-PINNING.md +++ b/docs/EXAMPLE-VERSION-PINNING.md @@ -1,269 +1,100 @@ -# How to Pin Specific Package Versions in Nix +# Nix Package Version Pinning -This guide shows how to use different versions of packages from different nixpkgs commits. +This guide describes the overrides in `flake.nix`. They apply to NixOS only; +macOS and Arch Linux packages come from `Brewfile` and `pacman-packages.txt`. -## Scenario +## Main package set -You want: -- **Package A** (e.g., neovim 0.11.5) from nixpkgs commit `abc123` -- **Package B** (e.g., ripgrep 14.0.0) from nixpkgs commit `def456` -- **Everything else** from the latest unstable +`nixpkgs` tracks `nixos-26.05` and Home Manager tracks `release-26.05`. +`flake.lock` pins their resolved commits. Updates are explicit: -## Step 1: Find the Right Commits - -### Method 1: Using nixpkgs commit history - -1. Go to https://github.com/NixOS/nixpkgs/commits/master -2. Search for commits that updated your package -3. Or use GitHub search: `repo:NixOS/nixpkgs neovim 0.11.5` - -### Method 2: Using search.nixos.org - -1. Visit https://search.nixos.org/packages -2. Search for your package (e.g., "neovim") -3. Select different channels/versions to see what's available -4. Note the channel name (e.g., `nixos-24.05`, `nixpkgs-unstable`) - -### Method 3: Using Nix CLI to check versions - -```bash -# Check version in current unstable -nix eval nixpkgs#neovim.version - -# Check version at a specific commit -nix eval github:NixOS/nixpkgs/abc123def456#neovim.version - -# Search for a package -nix search nixpkgs#neovim +```sh +nix flake update nixpkgs home-manager ``` -## Step 2: Update flake.nix - -Add additional nixpkgs inputs for each version you need: - -```nix -{ - description = "Gaiz's dotfiles - Nix flake configuration"; - - inputs = { - # Main nixpkgs (latest unstable) - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - - # Pinned version for Package A (neovim 0.11.5) - # Replace 'abc123def456' with actual commit hash - nixpkgs-neovim.url = "github:NixOS/nixpkgs/abc123def456"; - - # Pinned version for Package B (ripgrep 14.0.0) - # Replace 'def789ghi012' with actual commit hash - nixpkgs-ripgrep.url = "github:NixOS/nixpkgs/def789ghi012"; - - # You can also use branch names or tags - nixpkgs-stable.url = "github:NixOS/nixpkgs/nixos-24.11"; - - nix-darwin = { - url = "github:LnL7/nix-darwin"; - inputs.nixpkgs.follows = "nixpkgs"; - }; - - home-manager = { - url = "github:nix-community/home-manager"; - inputs.nixpkgs.follows = "nixpkgs"; - }; - }; - - outputs = { self, nixpkgs, nixpkgs-neovim, nixpkgs-ripgrep, nix-darwin, home-manager, ... }: - let - username = builtins.getEnv "USER"; - - # Helper to create package sets for different nixpkgs - mkPkgs = system: nixpkgsInput: import nixpkgsInput { - inherit system; - config.allowUnfree = true; - }; +This updates the lockfile, not the running system. Rebuild the selected NixOS +configuration afterward. - mkSystem = system: - let - pkgs = mkPkgs system nixpkgs; - pkgs-neovim = mkPkgs system nixpkgs-neovim; - pkgs-ripgrep = mkPkgs system nixpkgs-ripgrep; - in - nix-darwin.lib.darwinSystem { - inherit system; - modules = [ - home-manager.darwinModules.home-manager - { - nix.settings.experimental-features = "nix-command flakes"; - system.stateVersion = 5; +## Azure CLI: a separate nixpkgs revision - home-manager.useGlobalPkgs = true; - home-manager.useUserPackages = true; - home-manager.users.${username} = import ./home.nix; - - # Pass the custom package sets to home-manager - home-manager.extraSpecialArgs = { - inherit pkgs-neovim pkgs-ripgrep; - }; - } - ]; - }; - - mkHome = system: - let - pkgs = mkPkgs system nixpkgs; - pkgs-neovim = mkPkgs system nixpkgs-neovim; - pkgs-ripgrep = mkPkgs system nixpkgs-ripgrep; - in - home-manager.lib.homeManagerConfiguration { - inherit pkgs; - modules = [ - ./home.nix - ]; - # Pass the custom package sets to home.nix - extraSpecialArgs = { - inherit pkgs-neovim pkgs-ripgrep; - }; - }; - in - { - darwinConfigurations = { - "aarch64" = mkSystem "aarch64-darwin"; - "x86_64" = mkSystem "x86_64-darwin"; - }; - - homeConfigurations = { - "${username}-aarch64" = mkHome "aarch64-darwin"; - "${username}-x86_64" = mkHome "x86_64-darwin"; - }; - }; -} -``` - -## Step 3: Update home.nix - -Use the pinned packages in your home configuration: +The flake pins `nixpkgs-azure-cli` to +`286615174c6bd765907ef9975d0acdc799c7bf7e`, which provides Azure CLI 2.77.0. +It does not follow the main nixpkgs input. The overlay imports that package set +for the host system and exposes its Azure CLI: ```nix -{ config, pkgs, lib, pkgs-neovim ? pkgs, pkgs-ripgrep ? pkgs, ... }: - -let - username = builtins.getEnv "USER"; -in -{ - home.username = username; - home.homeDirectory = lib.mkDefault "/Users/${username}"; - home.stateVersion = "24.11"; - - programs.home-manager.enable = true; - - home.packages = [ - # Use default nixpkgs - pkgs.git - pkgs.fzf - pkgs.bat - - # Use pinned neovim from specific commit - pkgs-neovim.neovim - - # Use pinned ripgrep from specific commit - pkgs-ripgrep.ripgrep - ]; -} +azureCliOverlay = final: _prev: { + inherit (import inputs.nixpkgs-azure-cli { inherit (final.stdenv.hostPlatform) system; }) + azure-cli + ; +}; ``` -## Step 4: Lock and Build - -```bash -# Generate/update flake.lock -nix flake lock +`mkSystem` installs the overlay in `nixpkgs.overlays`. Because integrated Home +Manager uses the global package set, `pkgs.azure-cli` in +`home/modules/dev-tools.nix` resolves to the pinned version. -# Check what versions you'll get -nix eval .#homeConfigurations.${USER}-aarch64.config.home.packages.0.version +Inspect the actual package selected by the system: -# Build and activate -darwin-rebuild switch --flake .#aarch64 -# OR -home-manager switch --flake .#$USER-aarch64 +```sh +nix eval --raw '.#nixosConfigurations.nixos-wsl.pkgs.azure-cli.version' ``` -## Alternative: Using Overlays (Advanced) +To change it, choose a nixpkgs commit containing the desired package, change +the input URL, and run `nix flake lock`. Updating other inputs does not move +this explicit commit pin. -If you prefer, you can use overlays to override package versions: +## Copilot CLI: version and source override -```nix -# In home.nix -{ config, pkgs, lib, ... }: +`copilotOverlay` overrides the existing `github-copilot-cli` derivation's +version and source. It currently selects 1.0.70 and platform-specific +`linux-x64` / `linux-arm64` release archives, each with its own hash, while +retaining the nixpkgs packaging logic. -{ - nixpkgs.overlays = [ - # Override neovim to a specific version - (final: prev: { - neovim = prev.neovim.overrideAttrs (oldAttrs: rec { - version = "0.11.5"; - src = prev.fetchFromGitHub { - owner = "neovim"; - repo = "neovim"; - rev = "v${version}"; - hash = "sha256-..."; # Use nix-prefetch-url to get this - }; - }); - }) - ]; - - home.packages = with pkgs; [ - neovim # Will use overridden version - git - ]; -} +```sh +nix eval --raw '.#nixosConfigurations.nixos-wsl.pkgs.github-copilot-cli.version' ``` -## Finding Commit Hashes - -### Quick method using Nix: +When changing this override, update both the version and each supported +platform's archive hash in `flake.nix`. A version edit without matching hashes +is insufficient. Build the package before deploying: -```bash -# Find commits for a specific package version -nix-locate --at-root --top-level --whole-name "bin/nvim" | grep "neovim-0.11" - -# Or check nixpkgs history -git clone https://github.com/NixOS/nixpkgs --depth 1000 -cd nixpkgs -git log --all --grep="neovim.*0.11.5" --oneline +```sh +nix build --no-link '.#nixosConfigurations.nixos-wsl.pkgs.github-copilot-cli' ``` -### Using nixpkgs-review: +The flake comment links the upstream nixpkgs issue motivating this workaround. +Remove the overlay when the pinned main package set supplies the desired +working package. -```bash -# Search nixpkgs history -nix run nixpkgs#gh -- search commits --repo=NixOS/nixpkgs "neovim 0.11.5" -``` +## Claude Code and Herdr -## Summary +Claude Code comes from `claude-code-nix.overlays.default`. Herdr is installed +directly from `inputs.herdr.packages..default` in `terminal.nix`. +Both inputs follow the main nixpkgs package set and have their own revisions +recorded in `flake.lock`. -**For multiple package versions:** +```sh +nix flake update claude-code-nix herdr +``` -1. Add each nixpkgs input with desired commit/branch: - ```nix - nixpkgs-packageA.url = "github:NixOS/nixpkgs/"; - nixpkgs-packageB.url = "github:NixOS/nixpkgs/"; - ``` +## Adding another pin -2. Create package sets for each: - ```nix - pkgs-packageA = mkPkgs system nixpkgs-packageA; - ``` +Prefer the existing pattern: add a commit-pinned input when you need the +package and its dependency set from that revision, then add a narrowly scoped +overlay to `mkSystem`. For a source-only override, review whether the current +nixpkgs patches, dependencies, and build steps still apply to the new source. +Do not merely change `version` and assume the package source changed with it. -3. Pass them to home.nix: - ```nix - extraSpecialArgs = { inherit pkgs-packageA pkgs-packageB; }; - ``` +Keep overrides at the system package-set level so both NixOS and integrated +Home Manager see the same package. Review the lockfile diff to avoid unrelated +upgrades. -4. Use in home.nix: - ```nix - { pkgs, pkgs-packageA, pkgs-packageB, ... }: - home.packages = [ - pkgs-packageA.packageA - pkgs-packageB.packageB - ]; - ``` +```sh +nix flake check +sudo nixos-rebuild build --flake .#nixos-wsl +sudo nixos-rebuild switch --flake .#nixos-wsl +``` -This gives you complete control over each package's version! +Use `.#nixos-native` for the native host. Commit deliberate flake and lockfile +changes together. diff --git a/docs/IMPLEMENTATION_SUMMARY.md b/docs/IMPLEMENTATION_SUMMARY.md index a445dcd..209baf8 100644 --- a/docs/IMPLEMENTATION_SUMMARY.md +++ b/docs/IMPLEMENTATION_SUMMARY.md @@ -1,466 +1,41 @@ -# Implementation Summary - -## What Was Created - -A complete Nix flakes-based dotfiles architecture supporting three target platforms with maximum code reuse and reproducibility. - -## File Structure Created - -### Core Configuration Files - -``` -flake.nix # Main entry point, defines all outputs -├── NixOS configurations (nixosConfigurations) -│ ├── nixos-wsl # WSL2 system + home -│ └── nixos-native # Native NixOS system + home -├── Home Manager configurations (homeConfigurations) -│ ├── user@linux # Standalone for Archlinux (x86_64) -│ └── user@linux-arm64 # Standalone for Archlinux (ARM) -└── Darwin configurations (darwinConfigurations) - ├── aarch64 # macOS Apple Silicon - └── x86_64 # macOS Intel -``` - -### System Configurations (NixOS only) - -``` -systems/ -├── wsl/configuration.nix # WSL2-specific system settings -├── native/configuration.nix # Native NixOS system settings -└── darwin/configuration.nix # macOS system settings (nix-darwin) -``` - -**Key Features**: -- User account creation (`user3301`) -- Nix flakes enabled -- Automatic garbage collection -- Minimal system packages (most go in Home Manager) -- Platform-specific settings (WSL interop, desktop environment, macOS defaults) - -### Home Manager Configurations - -``` -home/ -├── nixos-wsl.nix # WSL2 user configuration -├── nixos-native.nix # Native NixOS user configuration -├── archlinux.nix # Archlinux user configuration -└── darwin.nix # macOS user configuration -``` - -**Key Features**: -- Imports shared modules -- Sets username and home directory -- Platform-specific packages -- Git user configuration - -### Shared Modules (Reusable Components) - -``` -home/modules/ -├── common.nix # Base configuration for all platforms -├── shell.nix # Zsh with plugins -├── dev-tools.nix # Development packages and tools -├── neovim.nix # Neovim with LSPs and formatters -└── terminal.nix # Herdr, Wezterm, Yazi -``` - -**Module Responsibilities**: - -| Module | Purpose | Packages | -|--------|---------|----------| -| common.nix | Base settings | Home Manager self-management, XDG, session vars | -| shell.nix | Shell config | Zsh with completion, syntax highlighting | -| dev-tools.nix | Dev tools | git, gh, lazygit, ripgrep, fd, bat, fzf, nil | -| neovim.nix | Neovim setup | LSPs (lua, nix, ts, python, rust, go), formatters | -| terminal.nix | Terminal apps | Herdr, Wezterm, Yazi | - -### Documentation - -``` -DEPLOYMENT.md # Detailed deployment guide (all platforms) -ARCHITECTURE.md # Architecture design and decisions -QUICK_REFERENCE.md # Command cheat sheet -README.nix.md # User-facing README -IMPLEMENTATION_SUMMARY.md # This file -``` - -## Architecture Highlights - -### 1. Platform Support Matrix - -| Feature | NixOS WSL2 | NixOS Native | Archlinux | macOS | -|---------|------------|--------------|-----------|-------| -| System Config | Yes | Yes | No | Yes (darwin) | -| Home Manager | Yes | Yes | Yes | Yes | -| Deployment Command | `nixos-rebuild` | `nixos-rebuild` | `home-manager` | `darwin-rebuild` | -| Username | user3301 | user3301 | user3301 (customizable) | gaiz | - -### 2. Code Reuse Strategy - -``` -All Platforms (100% shared) - └── home/modules/* (shell, dev-tools, neovim, terminal, editors) - │ - ├── NixOS WSL2 (system config + home config) - ├── NixOS Native (system config + home config) - ├── Archlinux (home config only) - └── macOS (darwin config + home config) -``` - -**Benefits**: -- **DRY**: Define package lists once, use everywhere -- **Consistency**: Same tools on all machines -- **Maintainability**: Update one module, affects all platforms -- **Flexibility**: Platform-specific overrides when needed - -### 3. Dotfiles Integration - -Your existing dotfiles are **symlinked**, not copied: - -``` -~/dotfiles/nvim/.config/nvim → ~/.config/nvim -~/dotfiles/herdr/.config/herdr → ~/.config/herdr -~/dotfiles/wezterm/.config/wezterm → ~/.config/wezterm -~/dotfiles/yazi/.config/yazi → ~/.config/yazi -``` - -**Why symlinks?** -- Edit configs directly (no rebuild needed for config changes) -- Preserve git history -- Compatible with manual management -- Works with GNU Stow if needed - -### 4. Deployment Workflows - -#### NixOS WSL2 -```bash -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-wsl -``` -**What happens**: -1. System configuration applied (user, WSL settings) -2. Home Manager packages installed -3. Dotfiles symlinked -4. Shell configured - -#### Archlinux -```bash -cd ~/dotfiles -home-manager switch --flake .#user@linux -``` -**What happens**: -1. Nix packages installed to user profile -2. Dotfiles symlinked -3. Shell configured -4. System packages (pacman) untouched - -### 5. Module Dependencies - -``` -common.nix (no dependencies) - │ - ├── shell.nix (uses common.home.homeDirectory) - │ - ├── dev-tools.nix (standalone) - │ │ - │ └── Provides tools for other modules - │ - ├── neovim.nix (uses dev-tools packages) - │ │ - │ └── Symlinks existing nvim config - │ - └── terminal.nix (standalone) - │ - └── Symlinks existing terminal configs -``` - -## Key Design Decisions - -### 1. Why Flakes? -- **Reproducibility**: Exact version pinning via flake.lock -- **Composability**: Easy to combine inputs -- **Portability**: Self-contained, no channel state -- **Modern**: Official Nix direction - -### 2. Why Separate System and Home Configs? -- **Portability**: Same user config works on NixOS and non-NixOS -- **Rollback**: Home Manager changes don't require system reboot -- **Separation**: Clear boundary between system and user concerns - -### 3. Why Symlinks Instead of Copying? -- **Live editing**: Change configs without rebuilding -- **Git integration**: Configs stay in version control -- **Familiarity**: Edit in expected locations -- **Performance**: No copying large configs - -### 4. Why Minimal System Packages? -- **Portability**: Same packages work on all platforms -- **Rollback**: Faster home-manager rollbacks -- **Separation**: System services in system config, everything else in home - -### 5. Why Multiple Home Configs Instead of One? -- **Clarity**: Each platform's config is explicit -- **Flexibility**: Easy platform-specific overrides -- **Maintainability**: No complex conditionals in shared code - -## Configuration Splitting Strategy - -### System Level (NixOS only) -**Location**: `systems/{wsl,native}/configuration.nix` - -**Includes**: -- Boot configuration -- User account creation -- System services (SSH, networking) -- Hardware configuration -- Desktop environment (native only) -- WSL settings (WSL only) - -**Excludes**: -- User packages (except minimal system tools) -- Dotfiles -- User-specific settings - -### User Level (All Platforms) -**Location**: `home/{platform}.nix` + `home/modules/*` - -**Includes**: -- All user packages -- Dotfiles symlinks -- Shell configuration -- Git configuration -- Application settings - -**Excludes**: -- System services -- Boot configuration -- User account management - -## Deployment Instructions by Platform - -### Initial Setup - -#### NixOS WSL2 -```bash -git clone ~/dotfiles -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-wsl -``` - -#### NixOS Native -```bash -git clone ~/dotfiles -cd ~/dotfiles -sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix -# Edit systems/native/configuration.nix to uncomment hardware import -# Customize desktop environment, graphics drivers -sudo nixos-rebuild switch --flake .#nixos-native -``` - -#### Archlinux -```bash -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install -git clone ~/dotfiles -cd ~/dotfiles -# Edit home/archlinux.nix to set your username -nix run home-manager/master -- switch --flake .#user@linux -``` - -### Subsequent Updates - -All platforms: -```bash -cd ~/dotfiles - -# Update flake inputs -nix flake update - -# Apply changes -sudo nixos-rebuild switch --flake .#nixos-wsl # NixOS -home-manager switch --flake .#user@linux # Archlinux -``` - -## Customization Points - -### Adding Packages - -**System-wide** (NixOS only): -```nix -# systems/wsl/configuration.nix -environment.systemPackages = with pkgs; [ - mypackage -]; -``` - -**User-level** (all platforms): -```nix -# home/modules/dev-tools.nix -home.packages = with pkgs; [ - mypackage -]; -``` - -### Adding Modules - -1. Create `home/modules/mymodule.nix` -2. Import in `home/{platform}.nix`: -```nix -imports = [ - ./modules/common.nix - ./modules/mymodule.nix -]; -``` - -### Platform-Specific Overrides - -```nix -# home/nixos-wsl.nix -imports = [ ./modules/common.nix ]; - -# Override from common -home.sessionVariables.EDITOR = "vim"; # Instead of nvim -``` - -### Conditional Packages - -```nix -# In any module -home.packages = with pkgs; [ - universal-package -] ++ lib.optionals stdenv.isLinux [ - linux-only-package -] ++ lib.optionals stdenv.isDarwin [ - macos-only-package -]; -``` - -## Testing Strategy - -### Before Deploying - -```bash -# Check syntax -nix flake check - -# Show what's defined -nix flake show - -# Build without activating -nix build .#nixosConfigurations.nixos-wsl.config.system.build.toplevel -``` - -### After Deploying - -```bash -# Test without switching -sudo nixos-rebuild test --flake .#nixos-wsl - -# If good, switch -sudo nixos-rebuild switch --flake .#nixos-wsl - -# If issues, rollback -sudo nixos-rebuild switch --rollback -``` - -## Migration Path - -### Phase 1: Minimal Deployment (Current) -- Basic system config -- Shared modules for dev tools -- Symlinks to existing dotfiles -- **Status**: Complete - -### Phase 2: Enhanced Modules (Optional) -- Language-specific dev environments -- More application configurations via Nix -- Platform-specific optimizations - -### Phase 3: Advanced Features (Optional) -- Custom NixOS modules -- Per-project development shells -- CI/CD integration - -### Phase 4: Full Declarative (Optional) -- All applications via Nix -- Automated backups -- Declarative VM/container configs - -## Next Steps - -### Immediate -1. **Test on target platforms**: Deploy to WSL2, native NixOS, or Archlinux -2. **Customize user info**: Update git username/email in home configs -3. **Adjust packages**: Add/remove packages in modules as needed - -### Short Term -1. **Generate hardware config**: For native NixOS deployment -2. **Customize desktop**: Choose desktop environment, graphics drivers -3. **Add more dotfiles**: Follow pattern in terminal.nix for new apps - -### Long Term -1. **Secrets management**: Manually manage SSH keys and sensitive credentials -2. **CI/CD**: Add GitHub Actions to test flake -3. **Development shells**: Create per-project flake.nix files -4. **Documentation**: Add your own notes and customizations - -## Troubleshooting Common Issues - -### "experimental features not enabled" -**Solution**: Add to NixOS config or `~/.config/nix/nix.conf`: -``` -experimental-features = nix-command flakes -``` - -### Conflicting files -**Solution**: Backup existing files before deploying: -```bash -mv ~/.config/nvim ~/.config/nvim.backup -``` - -### Module not found -**Solution**: Check import paths are relative to file location - -### Package not available -**Solution**: Search at search.nixos.org, verify attribute path - -## Files Summary - -Total files created: **19 Nix files + 4 documentation files** - -**Nix Configuration**: -- 1 flake.nix -- 3 system configurations (wsl, native, darwin) -- 4 home configurations (wsl, native, arch, darwin) -- 6 shared modules (common, shell, dev-tools, neovim, terminal, editors) - -**Documentation**: -- DEPLOYMENT.md (detailed deployment guide) -- ARCHITECTURE.md (design documentation) -- QUICK_REFERENCE.md (command cheat sheet) -- README.nix.md (user-facing README) -- IMPLEMENTATION_SUMMARY.md (this file) - -**Modified**: -- .gitignore (added hardware-configuration.nix exclusion) - -## Success Criteria - -This implementation is successful if: - -1. **Reproducible**: Same command produces same environment on any platform -2. **Modular**: Can enable/disable modules independently -3. **Flexible**: Works on NixOS and non-NixOS systems -4. **Maintainable**: Easy to add packages, modules, or platforms -5. **Documented**: Clear instructions for deployment and customization -6. **Preserves existing workflow**: Dotfiles can still be edited directly - -All criteria have been met with this implementation. - ---- - -**You now have a fully functional, reproducible, cross-platform dotfiles setup using Nix flakes!** - -Deploy with: -- **NixOS WSL2**: `sudo nixos-rebuild switch --flake .#nixos-wsl` -- **NixOS Native**: `sudo nixos-rebuild switch --flake .#nixos-native` -- **Archlinux**: `home-manager switch --flake .#user@linux` +# Current Configuration Summary + +| Platform | Managed by this repository | Not managed | +| --- | --- | --- | +| NixOS WSL2 | System, integrated Home Manager, packages, mutable config links, bootstrap checkout | Windows terminal setup | +| Native NixOS | System, integrated Home Manager, packages, mutable config links | Automatic hardware discovery or disk installation | +| macOS | Brewfile package installation and GNU Stow links | Nix configuration or macOS system preferences | +| Arch Linux | Root pacman package list and GNU Stow links | Nix configuration or system services | + +The NixOS outputs target x86_64. Linux x86_64 and ARM64 have repository quality +checks, a formatter, and a development shell. There are no standalone Home +Manager or Darwin outputs. + +## Shared files, separate package sets + +Application files remain Stow-compatible. NixOS links them with Home Manager's +`mkOutOfStoreSymlink`; macOS and Arch link them with Stow. NixOS expects the +checkout at `/home/user3301/dotfiles`. + +The eight Home Manager modules cover common settings, shells, development +tools, Git, Neovim, terminal tools, WezTerm, and language toolchains. They are +used only by the NixOS homes. Native package manifests are independent and +smaller; installing one does not reproduce the entire NixOS environment. + +Nix package sources are locked in `flake.lock`. Mutable config files, +Homebrew/pacman packages, Neovim plugin installation, Herdr plugins, and secrets +are not made reproducible by that lockfile. + +CI already runs GitHub Actions linting, four Nix flake quality checks, and WSL +configuration evaluation. It does not deploy machines or install native +macOS/Arch packages. + +## Documentation map + +| Guide | Purpose | +| --- | --- | +| [Deployment](DEPLOYMENT.md) | Platform setup, hardware, dependencies, local overrides | +| [NixOS](README.nix.md) | Rebuilds, updates, rollback, garbage collection | +| [Architecture](ARCHITECTURE.md) | Modules, outputs, symlinks, CI | +| [Quick reference](QUICK_REFERENCE.md) | Common commands and file locations | +| [Version pinning](EXAMPLE-VERSION-PINNING.md) | Current Nix package overrides | diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md index 1bb5153..738b338 100644 --- a/docs/QUICK_REFERENCE.md +++ b/docs/QUICK_REFERENCE.md @@ -1,474 +1,112 @@ -# Quick Reference Guide +# Quick Reference -## Bootstrap (First-Time Setup on Clean NixOS) +Run checkout commands from `~/dotfiles`. Read [deployment](DEPLOYMENT.md) for +prerequisites and conflict handling before the first setup. -**Problem**: No git on fresh NixOS install, but need git to clone dotfiles. +## macOS and Arch Linux -**Solution**: -```bash -# Get temporary git -nix-shell -p git -# or -nix run nixpkgs#git -- clone https://github.com/user3301/dotfiles.git ~/dotfiles +| Task | macOS | Arch Linux | +| --- | --- | --- | +| Install/update manifest packages | `brew bundle --file=Brewfile` | `sudo pacman -Syu --needed - < pacman-packages.txt` | +| Install packages and link dotfiles | `make setup-mac` | `make setup-arch` | +| Package manifest | `Brewfile` | `pacman-packages.txt` | -# Clone and deploy -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-wsl # or .#nixos-native -exit # Exit nix-shell if used - -# Now git is permanently installed! -``` - -See full bootstrap guide in [DEPLOYMENT.md](DEPLOYMENT.md#bootstrap-process-first-time-setup-on-clean-nixos). - ---- +Homebrew must already be on `PATH` for `make setup-mac`. Stow does not install +shell frameworks or missing applications; the manifests are not the full NixOS +package set. -## Common Commands by Platform +```sh +# Default non-AeroSpace links +make stow -### NixOS WSL2 +# Select only desired packages +make stow STOW_PACKAGES="git nvim" -```bash -# Deploy/update system -sudo nixos-rebuild switch --flake .#nixos-wsl +# Preview a selection +stow --simulate --verbose --target="$HOME" git nvim -# Test without switching -sudo nixos-rebuild test --flake .#nixos-wsl +# Remove only Stow-managed links for a selection +stow --delete --target="$HOME" git nvim -# Build without activating -sudo nixos-rebuild build --flake .#nixos-wsl - -# Show what will change -sudo nixos-rebuild dry-run --flake .#nixos-wsl - -# Rollback to previous generation -sudo nixos-rebuild switch --rollback - -# List generations -sudo nix-env --list-generations --profile /nix/var/nix/profiles/system +# macOS-only configuration +stow --target="$HOME" aerospace ``` -### NixOS Native +`make stow` selects `bash fastfetch git herdr lazygit nvim wezterm yazi zsh`. +`make setup-mac` adds `aerospace`. Do not Stow paths managed by Home Manager. -```bash -# Deploy/update system -sudo nixos-rebuild switch --flake .#nixos-native - -# Same options as WSL2 (test, build, dry-run, rollback) -``` - -### Archlinux (or other Linux with Home Manager) - -```bash -# First-time setup (if home-manager not installed) -nix run home-manager/master -- switch --flake .#user@linux +## NixOS WSL2 -# Update configuration -home-manager switch --flake .#user@linux +```sh +# Bootstrap an existing NixOS-WSL installation +nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl -# Test without switching -home-manager build --flake .#user@linux -./result/activate - -# List generations -home-manager generations +# After restarting WSL from PowerShell with wsl --shutdown: +cd ~/dotfiles +make switch -# Rollback -home-manager switch --rollback +# Build without activation +make build -# Or rollback to specific generation -/nix/var/nix/profiles/per-user/$USER/home-manager-42-link/activate +# Update locked inputs, then rebuild +make update +make switch ``` -### macOS (nix-darwin) +For an existing checkout, `make setup-wsl-nixos` stages the configuration with +`nixos-rebuild boot`; it requires a WSL restart. -```bash -# Deploy/update (Apple Silicon) -darwin-rebuild switch --flake .#aarch64 +## Native NixOS -# Deploy/update (Intel) -darwin-rebuild switch --flake .#x86_64 +Replace the VirtualBox hardware import before deploying to another machine. -# Using Makefile -make update-home-manager +```sh +sudo nixos-rebuild build --flake .#nixos-native +sudo nixos-rebuild switch --flake .#nixos-native ``` -## Flake Management +## Nix maintenance -```bash -# Update all inputs -nix flake update - -# Update specific input -nix flake lock --update-input nixpkgs -nix flake lock --update-input home-manager - -# Show flake info +```sh nix flake show - -# Check for errors -nix flake check - -# Show flake metadata -nix flake metadata -``` - -## Package Management - -### Search for packages - -```bash -# Online search (recommended) -# Visit: https://search.nixos.org/packages - -# Command line search -nix search nixpkgs - -# Example -nix search nixpkgs neovim -``` - -### Install package temporarily - -```bash -# Run without installing -nix run nixpkgs#hello - -# Start shell with package -nix shell nixpkgs#hello nixpkgs#cowsay - -# Run specific version -nix run github:nixos/nixpkgs/nixos-23.11#hello -``` - -### Add package permanently - -Edit appropriate file: - -**System packages** (NixOS only): -```nix -# systems/{wsl,native}/configuration.nix -environment.systemPackages = with pkgs; [ - mypackage -]; -``` - -**User packages** (all platforms): -```nix -# home/modules/dev-tools.nix or platform-specific home config -home.packages = with pkgs; [ - mypackage -]; -``` - -Then rebuild: -```bash -# NixOS -sudo nixos-rebuild switch --flake .#nixos-wsl - -# Home Manager (Archlinux, etc.) -home-manager switch --flake .#user@linux -``` - -## Editing Configurations - -### File locations - -| What | Where | -|------|-------| -| Main flake | `/Users/gaiz/dotfiles/flake.nix` | -| WSL system | `/Users/gaiz/dotfiles/systems/wsl/configuration.nix` | -| Native system | `/Users/gaiz/dotfiles/systems/native/configuration.nix` | -| WSL home | `/Users/gaiz/dotfiles/home/nixos-wsl.nix` | -| Native home | `/Users/gaiz/dotfiles/home/nixos-native.nix` | -| Arch home | `/Users/gaiz/dotfiles/home/archlinux.nix` | -| Common module | `/Users/gaiz/dotfiles/home/modules/common.nix` | -| Dev tools | `/Users/gaiz/dotfiles/home/modules/dev-tools.nix` | - -### Editing workflow - -```bash -# 1. Edit configuration files -vim ~/dotfiles/home/modules/dev-tools.nix - -# 2. Check for syntax errors nix flake check - -# 3. Test the changes -sudo nixos-rebuild test --flake .#nixos-wsl - -# 4. If good, apply permanently -sudo nixos-rebuild switch --flake .#nixos-wsl - -# 5. Commit changes -git add . -git commit -m "Add new package" -git push -``` - -## Dotfiles Management - -### Symlinked configs - -Your existing dotfiles are symlinked from: -- `~/dotfiles/nvim/.config/nvim` → `~/.config/nvim` -- `~/dotfiles/herdr/.config/herdr` → `~/.config/herdr` -- `~/dotfiles/wezterm/.config/wezterm` → `~/.config/wezterm` -- etc. - -You can edit them directly: -```bash -# Edit neovim config -vim ~/dotfiles/nvim/.config/nvim/init.lua - -# Changes are immediately available (no rebuild needed) -``` - -### Adding new dotfile - -1. Add directory structure: -```bash -mkdir -p ~/dotfiles/myapp/.config/myapp -cp -r ~/.config/myapp/* ~/dotfiles/myapp/.config/myapp/ -``` - -2. Create or update module: -```nix -# home/modules/myapp.nix -{ config, pkgs, lib, ... }: -{ - programs.myapp.enable = true; - - xdg.configFile."myapp".source = config.lib.file.mkOutOfStoreSymlink - "${config.home.homeDirectory}/dotfiles/myapp/.config/myapp"; -} -``` - -3. Import in home config: -```nix -# home/nixos-wsl.nix -imports = [ - ./modules/common.nix - ./modules/myapp.nix -]; -``` - -4. Rebuild - -## Garbage Collection - -```bash -# Delete old generations (7+ days) -nix-collect-garbage --delete-older-than 7d - -# Delete all old generations (NixOS) -sudo nix-collect-garbage -d - -# Delete all old generations (Home Manager) -nix-collect-garbage -d - -# Remove old boot entries (NixOS) -sudo nix-env --delete-generations old --profile /nix/var/nix/profiles/system -sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot - -# Optimize store (remove duplicate files) -nix-store --optimise -``` - -## Troubleshooting - -### Build failures - -```bash -# Show detailed error -nix build --show-trace .#nixosConfigurations.nixos-wsl.config.system.build.toplevel - -# Clean build cache -nix-collect-garbage -d -sudo nix-collect-garbage -d -``` - -### Conflicting files - -```bash -# Find conflicts -home-manager switch --flake .#user@linux - -# If it shows conflicting files, back them up -mv ~/.config/nvim ~/.config/nvim.backup - -# Then rebuild -home-manager switch --flake .#user@linux -``` - -### Rollback - -```bash -# NixOS: List generations -sudo nix-env --list-generations --profile /nix/var/nix/profiles/system - -# NixOS: Switch to generation 42 -sudo nix-env --switch-generation 42 --profile /nix/var/nix/profiles/system -sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch - -# Home Manager: List generations -home-manager generations - -# Home Manager: Activate generation -/nix/var/nix/profiles/per-user/$USER/home-manager-42-link/activate -``` - -### Reset to clean state - -```bash -# ⚠️ DESTRUCTIVE: This will remove all Nix-installed packages - -# Remove all generations -nix-collect-garbage -d -sudo nix-collect-garbage -d - -# Reinstall from scratch -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-wsl -``` - -## Platform-Specific Quick Tips - -### WSL2 - -```bash -# Access Windows files -cd /mnt/c/Users/YourName - -# Run Windows command -cmd.exe /c dir - -# Open file in Windows app -explorer.exe . -``` - -### Archlinux - -```bash -# Update both Arch and Nix packages -sudo pacman -Syu && home-manager switch --flake .#user@linux - -# Install system package (use pacman) -sudo pacman -S docker - -# Install dev tool (use Nix) -# Add to home/modules/dev-tools.nix, then: -home-manager switch --flake .#user@linux -``` - -### macOS - -```bash -# Update Homebrew apps -brew update && brew upgrade - -# Update Nix configuration -darwin-rebuild switch --flake .#aarch64 - -# Both -brew upgrade && darwin-rebuild switch --flake .#aarch64 -``` - -## Development Shells - -### Project-specific environment - -Create `flake.nix` in project directory: - -```nix -{ - description = "My project"; - - inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - - outputs = { self, nixpkgs }: - let - system = "x86_64-linux"; - pkgs = import nixpkgs { inherit system; }; - in { - devShells.${system}.default = pkgs.mkShell { - buildInputs = with pkgs; [ - nodejs - python3 - postgresql - ]; - }; - }; -} -``` - -Enter shell: -```bash nix develop -``` - -Or use direnv: -```bash -echo "use flake" > .envrc -direnv allow -# Now auto-loads when you cd into directory -``` - -## Useful Environment Variables - -```bash -# See what's in your PATH -echo $PATH +nix fmt -- flake.nix -# See all Nix profiles -ls -la ~/.nix-profile/ - -# See current system profile (NixOS) -ls -la /run/current-system - -# See current home-manager profile -ls -la ~/.local/state/home-manager/ - -# NIX_PATH (usually not needed with flakes) -echo $NIX_PATH -``` - -## Getting Help - -```bash -# NixOS options search -https://search.nixos.org/options - -# Home Manager options search -https://mipmip.github.io/home-manager-option-search/ - -# Nix command help -nix --help -nix build --help - -# Man pages -man configuration.nix -man home-configuration.nix -``` - -## Cheat Sheet - -| Task | NixOS | Home Manager (Arch) | -|------|-------|---------------------| -| Deploy | `sudo nixos-rebuild switch --flake .#nixos-wsl` | `home-manager switch --flake .#user@linux` | -| Test | `sudo nixos-rebuild test --flake .#nixos-wsl` | `home-manager build --flake .#user@linux; ./result/activate` | -| Rollback | `sudo nixos-rebuild switch --rollback` | `home-manager switch --rollback` | -| Update | `nix flake update` | `nix flake update` | -| GC | `sudo nix-collect-garbage -d` | `nix-collect-garbage -d` | -| List gens | `sudo nix-env --list-generations --profile /nix/var/nix/profiles/system` | `home-manager generations` | - ---- - -**Pro tip**: Alias common commands in your shell: +nix flake update +nix flake update nixpkgs home-manager -```bash -# Add to ~/.zshrc or equivalent -alias nrs="sudo nixos-rebuild switch --flake ~/dotfiles#nixos-wsl" -alias nrt="sudo nixos-rebuild test --flake ~/dotfiles#nixos-wsl" -alias hms="home-manager switch --flake ~/dotfiles#user@linux" -alias nfu="nix flake update" -``` +sudo nixos-rebuild switch --rollback +sudo nix-env --list-generations --profile /nix/var/nix/profiles/system +nix-collect-garbage +``` + +`nixos-rebuild test --flake .#nixos-wsl` activates temporarily; `build` does not. +System rollback does not revert linked files in the mutable checkout. +`make clean` deletes generations older than seven days and runs GC; use it only +when those rollback points are no longer needed. + +Home Manager is integrated into the NixOS rebuild, not exposed as a standalone +flake output. + +## Where to edit + +| Change | File | +| --- | --- | +| Nix inputs, overlays, outputs, checks | `flake.nix` | +| WSL system services/user | `systems/wsl/configuration.nix` | +| Native hardware import/desktop/services | `systems/native/configuration.nix` | +| NixOS user identity/platform packages | `home/nixos-wsl.nix`, `home/nixos-native.nix` | +| Shared NixOS user packages | `home/modules/` | +| Application settings | Respective Stow package | +| Local Git identity/signing | `git/.config/git/config.local` (ignored) | +| Local Zsh settings | `zsh/.zshenv.local` (ignored) | +| Local interactive Bash settings | `bash/.bashrc.local` (ignored) | + +Reload applications after editing their linked config. Rebuild NixOS for Nix +changes; rerun Stow for new linked paths. Use `git add` for new files that a +Git-backed flake must include. + +`make help` lists the available helpers. Full CI commands are in +[Architecture](ARCHITECTURE.md#existing-ci); package override details are in +[Version pinning](EXAMPLE-VERSION-PINNING.md). diff --git a/docs/README.nix.md b/docs/README.nix.md index 2fc0432..683d89a 100644 --- a/docs/README.nix.md +++ b/docs/README.nix.md @@ -1,365 +1,135 @@ -# Cross-Platform Dotfiles with Nix Flakes +# NixOS Dotfiles -Fully reproducible dotfiles configuration supporting: -- **NixOS WSL2** (Windows Subsystem for Linux) -- **NixOS Native** (bare metal or VM) -- **Archlinux** with Nix + Home Manager -- **macOS** with nix-darwin +Nix manages **native NixOS and NixOS WSL2 only**. For macOS (Homebrew + Stow) or +Arch Linux (pacman + Stow), use the [deployment guide](DEPLOYMENT.md). -> "Dotfiles managed by Nix: because spending 40 hours to save 4 minutes is a lifestyle. Fully reproducible - I've tested it on my Windows gaming rig (NixOS-WSL2), my wife's MacBook Air, and my own laptop (I use Arch BTW). If it works there, it'll work anywhere." +## First deployment -## Quick Start +The repository includes `flake.lock`; use those revisions for the initial +deployment rather than updating inputs immediately. -For Nix installation prerequisites and alternative installers, see the [deployment guide](DEPLOYMENT.md#prerequisites). The repository includes `flake.lock`; use it for the initial deployment rather than updating package versions. +On an existing NixOS-WSL distribution: -After the first Nix build on a new machine, manually install the Herdr plugins [Auto Title](https://github.com/kryptamine/herdr-auto-title) and [reviewr](https://github.com/persiyanov/herdr-reviewr). These two plugins are not managed by Nix. - -Choose your platform: - -### NixOS WSL2 - -On a fresh NixOS-WSL installation, run: - -```bash +```sh nix --extra-experimental-features 'nix-command flakes' run github:user3301/dotfiles#bootstrap-wsl ``` -`nixos-anywhere` is not used here because WSL has already created and mounted -the distribution's virtual disk; `nixos-anywhere` is intended to provision an -SSH target and normally repartition its disks. +This creates the `user3301` configuration and clones the mutable checkout into +`/home/user3301/dotfiles` before Home Manager activation. Restart with +`wsl --shutdown` from PowerShell and reopen the distribution. -The bootstrap configuration clones the repository to -`/home/user3301/dotfiles` as part of NixOS activation, before Home Manager -starts. This remains reliable even when changing WSL's default user terminates -the original shell session. It is safe to rerun after an interrupted bootstrap. -When it completes, run `wsl --shutdown` from PowerShell and reopen the -distribution. +For native NixOS, first clone the checkout and replace the checked-in +VirtualBox hardware import as described in +[Native NixOS deployment](DEPLOYMENT.md#native-nixos). Then: -### NixOS Native -```bash -git clone ~/dotfiles -cd ~/dotfiles - -# Generate hardware config first -sudo nixos-generate-config --show-hardware-config > systems/native/hardware-configuration.nix - -# Edit systems/native/configuration.nix to uncomment hardware import -# Then deploy +```sh sudo nixos-rebuild switch --flake .#nixos-native ``` -### Archlinux + Nix/Home Manager - -Also suitable for other Linux distributions. Check your architecture with `uname -m` and choose the matching command below. +Both host configurations are x86_64 and integrate Home Manager. There is no +separate `home-manager switch --flake` workflow. Most packages and application +links are defined in `home/modules/`; system settings are under `systems/`. -```bash -# Install Nix first -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +## Editing and applying changes -git clone https://github.com/user3301/dotfiles.git ~/dotfiles +```sh cd ~/dotfiles -# Edit home/archlinux.nix to set home.username and home.homeDirectory -# Then deploy on x86_64 Linux: -nix run home-manager/master -- switch --flake .#user@linux - -# Or on ARM64 Linux: -nix run home-manager/master -- switch --flake .#user@linux-arm64 -``` - -The `user@linux` and `user@linux-arm64` names are fixed flake outputs, not placeholders for your username. - -### macOS + nix-darwin - -From the repository checkout, install Nix, activate nix-darwin with Home Manager, and install Homebrew apps: - -```bash -make setup-mac -``` - -If Nix is already installed, activate the Nix configuration directly instead: - -```bash -uname -m - -# Apple Silicon (uname -m reports arm64): -nix run nix-darwin -- switch --flake .#aarch64 - -# Intel (uname -m reports x86_64): -nix run nix-darwin -- switch --flake .#x86_64 -``` - -Before activation, customize `home.username` and `home.homeDirectory` in `home/darwin.nix` and the corresponding `home-manager.users` key in `flake.nix` if needed. Usernames and home directories are configured explicitly, not detected from `$USER`. Home Manager is integrated with nix-darwin; this flake does not provide standalone macOS Home Manager outputs. - -## What's Included - -### Development Tools -- **Editors**: Neovim -- **Terminal**: Herdr, Wezterm, Yazi -- **Shell**: Zsh (primary, oh-my-zsh + mcfly) with a minimal Bash fallback (zoxide + mcfly) -- **Version Control**: Git, GitHub CLI, Lazygit -- **CLI Tools**: ripgrep, fd, bat, fzf, jq, and more -- **Rust Toolchain**: rustc, Cargo, Clippy, and rustfmt (managed by Nix) -- **Language Servers**: For Nix, Lua, TypeScript, Python, Rust, Go +# WSL: rebuild the system and integrated home together +make switch -### Configuration Management -- **Modular**: Shared modules + platform-specific overrides -- **Symlinked**: Your existing dotfiles are symlinked (edit directly, no rebuild needed) -- **Stow-compatible**: each top-level config directory is also a GNU Stow package, so the same repo works on non-Nix machines (`stow bash zsh nvim`) -- **Reproducible**: Same environment across all machines -- **Declarative**: Everything in version control - -## Directory Structure - -``` -dotfiles/ -├── flake.nix # Main configuration entry point -│ -├── home/ # Home Manager configurations -│ ├── modules/ # Shared modules -│ │ ├── common.nix # Base settings -│ │ ├── shell.nix # Zsh + Bash configuration -│ │ ├── dev-tools.nix # Development packages -│ │ ├── neovim.nix # Neovim + LSPs -│ │ └── terminal.nix # Herdr, Wezterm, Yazi -│ │ -│ ├── nixos-wsl.nix # WSL2 home config -│ ├── nixos-native.nix # Native NixOS home config -│ ├── archlinux.nix # Archlinux home config -│ └── darwin.nix # macOS home config -│ -├── systems/ # NixOS system configurations -│ ├── wsl/ -│ │ └── configuration.nix # WSL2 system config -│ ├── native/ -│ │ └── configuration.nix # Native NixOS system config -│ └── darwin/ -│ └── configuration.nix # macOS system config -│ -├── [existing dotfiles]/ # Your actual configs -│ ├── nvim/.config/nvim/ -│ ├── herdr/.config/herdr/ -│ ├── wezterm/.config/wezterm/ -│ ├── yazi/.config/yazi/ -│ ├── zsh/ -│ └── bash/ # Minimal fallback shell -│ -└── docs/ - ├── DEPLOYMENT.md # Detailed deployment guide - ├── ARCHITECTURE.md # Architecture documentation - └── QUICK_REFERENCE.md # Command cheat sheet +# Native NixOS +sudo nixos-rebuild switch --flake .#nixos-native ``` -## Documentation +Edit shared user packages in the appropriate `home/modules/*.nix` file, or +platform packages in `home/nixos-wsl.nix` / `home/nixos-native.nix`. Add new +modules to the selected home's imports. Git-backed flakes exclude new, +untracked files until they are added with `git add`. -- **[DEPLOYMENT.md](DEPLOYMENT.md)**: Detailed deployment instructions for each platform -- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Architecture design and rationale -- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)**: Command cheat sheet and quick tips +Application configuration is linked to the checkout, so editing Lua, TOML, +shell, or Git config normally only needs an application reload. Do not Stow +over the links managed by Home Manager. Git identity belongs in the ignored +`git/.config/git/config.local`, not a generated `programs.git` configuration. -## Common Tasks - -### Update Configuration -```bash -# NixOS -cd ~/dotfiles -sudo nixos-rebuild switch --flake .#nixos-wsl +Keep `system.stateVersion` and `home.stateVersion` at their existing values +unless you have reviewed the relevant migration guidance. They select +compatibility defaults; they are not the package channel version. -# Archlinux / other Linux (use .#user@linux-arm64 on ARM64) -cd ~/dotfiles -home-manager switch --flake .#user@linux +## Updating packages -# macOS Apple Silicon (use .#x86_64 on Intel) +```sh cd ~/dotfiles -darwin-rebuild switch --flake .#aarch64 -``` +nix flake update # all inputs +# Or update only selected inputs: +nix flake update nixpkgs home-manager -### Add New Package -Edit `home/modules/dev-tools.nix`: -```nix -home.packages = with pkgs; [ - # Add your package here - htop -]; +sudo nixos-rebuild switch --flake .#nixos-wsl +# Use .#nixos-native for the native host ``` -Then rebuild. -### Update All Packages -```bash -nix flake update -``` +Review and commit `flake.lock` alongside intentional input changes. Updating +the lockfile alone does not activate packages. The Azure CLI revision and +Copilot CLI version/hash override require deliberate edits; see +[version pinning](EXAMPLE-VERSION-PINNING.md). -Then run your platform's command under [Update Configuration](#update-configuration) to activate the updated packages. Commit the updated `flake.lock` to keep package versions reproducible. +`make update` updates inputs; `make upgrade` updates and rebuilds WSL. +`make switch`, `make build`, and `make upgrade` are WSL-specific, not host +auto-detection commands. -### Inspect the Flake and Search Packages -```bash -# Check the configuration -nix flake check +## Validation and troubleshooting -# Show available outputs +```sh nix flake show +nix flake check -# Search for a package -nix search nixpkgs -``` - -### Rollback -```bash -# NixOS -sudo nixos-rebuild switch --rollback - -# Home Manager -home-manager switch --rollback -``` - -## Platform-Specific Features - -### NixOS WSL2 -- Full NixOS experience on Windows -- WSL interoperability enabled -- Windows paths accessible via `/mnt/c/` -- Username: `user3301` - -### NixOS Native -- Full system control -- Hardware configuration included -- Desktop environment support -- Username: `user3301` - -### Archlinux + Nix/Home Manager -- Best of both worlds (pacman + Nix) -- System packages via pacman -- User packages via Nix -- Gradual migration path - -### macOS + nix-darwin -- System settings via Nix -- GUI apps via Homebrew (Brewfile) -- User configs via Home Manager - -## Design Principles - -1. **Reproducibility**: Same command, same result, every time -2. **Modularity**: Shared code across platforms, platform-specific when needed -3. **Flexibility**: Works on NixOS and non-NixOS systems -4. **Familiarity**: Preserves your existing dotfiles structure -5. **Separation**: System vs. user configuration - -## Advanced Features - -### Secrets Management -**Current approach**: Manual management for simplicity -- Generate SSH keys manually on each machine: `ssh-keygen -t ed25519` -- Keep sensitive credentials outside version control -- Use local overrides (`.zshenv.local` / `.bashrc.local` pattern) for machine-specific secrets - -### Development Shells -Create project-specific environments: -```nix -# In your project directory -{ - inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - outputs = { nixpkgs, ... }: { - devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell { - buildInputs = [ nodejs python3 ]; - }; - }; -} -``` - -Then: `nix develop` +# Build without activation +sudo nixos-rebuild build --flake .#nixos-wsl -### CI/CD -Add GitHub Actions to test configurations: -```yaml -- name: Check flake - run: nix flake check +# Evaluate with a trace if necessary +nix eval --show-trace --raw \ + '.#nixosConfigurations.nixos-wsl.config.system.build.toplevel.drvPath' ``` -## Troubleshooting +`nixos-rebuild test` **does activate** the configuration, but does not make it +the boot default. Use `build` when you want no running-system changes. -### "experimental features not enabled" -```bash -# NixOS: Add to configuration.nix -nix.settings.experimental-features = [ "nix-command" "flakes" ]; +CI's narrower quality/evaluation commands are listed in +[Architecture](ARCHITECTURE.md#existing-ci). Native hardware must be reviewed +on the target machine even if evaluation succeeds. -# Non-NixOS: Add to ~/.config/nix/nix.conf -experimental-features = nix-command flakes -``` +For initial commands on a system without flakes enabled, use +`nix --extra-experimental-features 'nix-command flakes' ...`. The bootstrap app +also enables those features for its rebuild. -### Conflicting files -```bash -# Backup existing configs -mv ~/.config/nvim ~/.config/nvim.backup +If Home Manager reports a file conflict, inspect and back up that specific +path, then rebuild. Do not force replacement of the entire `~/.config` +directory. Inspect activation failures with: -# Then rebuild -home-manager switch --flake .#user@linux +```sh +journalctl -u home-manager-user3301.service -b ``` -### Build errors -```bash -# Show detailed trace -nix build --show-trace .#nixosConfigurations.nixos-wsl.config.system.build.toplevel +## Rollback and garbage collection -# Clean and rebuild -nix-collect-garbage -d -sudo nixos-rebuild switch --flake .#nixos-wsl +```sh +sudo nixos-rebuild switch --rollback +make generations +make gc ``` -## Migration Guide - -### From existing non-Nix setup -1. Start with minimal configuration -2. Add modules incrementally -3. Test each change -4. Keep backups during transition - -### From NixOS without flakes -1. Enable flakes in current config -2. Rebuild with `nixos-rebuild switch` -3. Clone this repo -4. Switch to flake: `sudo nixos-rebuild switch --flake .#nixos-wsl` - -### From home-manager without flakes -1. Backup current config -2. Install from this repo -3. Gradually migrate custom settings - -## Contributing - -Feel free to: -- Report issues -- Suggest improvements -- Share your configurations -- Submit pull requests - -## Resources - -- [NixOS Manual](https://nixos.org/manual/nixos/stable/) -- [Home Manager Manual](https://nix-community.github.io/home-manager/) -- [Nix Pills](https://nixos.org/guides/nix-pills/) -- [NixOS Discourse](https://discourse.nixos.org/) -- [NixOS Wiki](https://nixos.wiki/) - -## FAQ - -**Q: Why Nix?** -A: Reproducibility, declarative configuration, and one package manager to rule them all. - -**Q: Can I use this on Ubuntu/Fedora?** -A: Yes! Use the Archlinux configuration as a template (standalone Home Manager). - -**Q: Do I need to use Nix for everything?** -A: No. You can keep using your OS package manager for system packages and use Nix for user-level tools. - -**Q: What if I want to customize?** -A: All configurations are modular. Edit the relevant module or create a new one. - -**Q: How do I update packages?** -A: `nix flake update` updates all inputs, then rebuild your configuration. +Integrated Home Manager packages and generated configuration belong to the +system generation. Mutable symlink targets are not rolled back; restore +application files separately from Git if necessary. -**Q: Can I test changes without breaking my system?** -A: Yes! Use `sudo nixos-rebuild test` or `home-manager build` to test first. +Both NixOS systems enable weekly garbage collection with seven-day retention. +`make clean` runs `sudo nix-collect-garbage --delete-older-than 7d`; this removes +older system generations and can eliminate rollback options. It is not a +build-error recovery step. ---- +## Manual components -**Remember**: The goal is reproducibility. Once configured, you can deploy this exact environment on any new machine with a single command! +LazyVim downloads plugins independently of Nix. Herdr's Auto Title and reviewr +plugins need manual installation. SSH keys, signing keys, and credentials are +not provisioned. See [deployment](DEPLOYMENT.md#local-settings-and-manual-steps) +and the [Neovim README](../nvim/.config/nvim/README.md). diff --git a/flake.lock b/flake.lock index 16fb6c4..af5a890 100644 --- a/flake.lock +++ b/flake.lock @@ -79,26 +79,6 @@ "type": "github" } }, - "nix-darwin": { - "inputs": { - "nixpkgs": [ - "nixpkgs" - ] - }, - "locked": { - "lastModified": 1786845137, - "narHash": "sha256-oQFip+v0luP8NIxJzmiW4Wu8bILsbFWom5l0zonl8hQ=", - "owner": "LnL7", - "repo": "nix-darwin", - "rev": "4cff07de74b50e64bdd68cd4e722ab5b6b35ee48", - "type": "github" - }, - "original": { - "owner": "LnL7", - "repo": "nix-darwin", - "type": "github" - } - }, "nixos-wsl": { "inputs": { "flake-compat": "flake-compat", @@ -157,7 +137,6 @@ "claude-code-nix": "claude-code-nix", "herdr": "herdr", "home-manager": "home-manager", - "nix-darwin": "nix-darwin", "nixos-wsl": "nixos-wsl", "nixpkgs": "nixpkgs", "nixpkgs-azure-cli": "nixpkgs-azure-cli" diff --git a/flake.nix b/flake.nix index 3c191f3..d7daf1b 100644 --- a/flake.nix +++ b/flake.nix @@ -1,5 +1,5 @@ { - description = "user3301's' dotfiles for NixOS, NixOS WSL2, and Archlinux"; + description = "user3301's dotfiles for native NixOS and NixOS WSL2"; inputs = { # Nixpkgs - stable release @@ -27,12 +27,6 @@ inputs.nixpkgs.follows = "nixpkgs"; }; - # Nix Darwin - for macOS support (optional, keeping for your current setup) - nix-darwin = { - url = "github:LnL7/nix-darwin"; - inputs.nixpkgs.follows = "nixpkgs"; - }; - # Pinned nixpkgs providing azure-cli 2.77.0 (nixpkgs went 2.75.0 -> 2.77.0 # directly; 2.76.0 was never packaged). Deliberately not following the # main nixpkgs input, since the whole point is to freeze this one package. @@ -45,15 +39,12 @@ nixpkgs, home-manager, nixos-wsl, - nix-darwin, ... }@inputs: let supportedSystems = [ "x86_64-linux" "aarch64-linux" - "x86_64-darwin" - "aarch64-darwin" ]; forAllSystems = nixpkgs.lib.genAttrs supportedSystems; @@ -70,8 +61,6 @@ { "x86_64-linux" = "linux-x64"; "aarch64-linux" = "linux-arm64"; - "x86_64-darwin" = "darwin-x64"; - "aarch64-darwin" = "darwin-arm64"; } .${prev.stdenv.hostPlatform.system}; in @@ -83,8 +72,6 @@ { "x86_64-linux" = "sha256-z70Rb+FZviiaut8sK/GKJairCe7KVKCR1AJeHLzaRwk="; "aarch64-linux" = "sha256-saIHbLOlh+uivG9HjONeU/IKNNDWm0GAdDmzMC3191o="; - "x86_64-darwin" = "sha256-biISO2sXX+HWeGo+4vXRu3M9BN839sFBN0McAcPBWNI="; - "aarch64-darwin" = "sha256-Tr+isxFUmWQgQX3ivglJ7x9ONa8JQ9ZVFUdNWuPCKxE="; } .${prev.stdenv.hostPlatform.system}; }; @@ -123,35 +110,6 @@ }; }; - # Helper function for standalone Home Manager (Archlinux, etc.) - mkHome = - { - system, - modules, - }: - home-manager.lib.homeManagerConfiguration { - pkgs = import nixpkgs { - inherit system; - config.allowUnfree = true; - overlays = [ - claudeOverlay - copilotOverlay - azureCliOverlay - ]; - }; - inherit modules; - extraSpecialArgs = { inherit inputs; }; - }; - - # Helper function for nix-darwin (macOS) - mkDarwin = - { system, modules }: - nix-darwin.lib.darwinSystem { - inherit system; - inherit modules; - specialArgs = { inherit inputs; }; - }; - wslSystemModules = [ nixos-wsl.nixosModules.wsl ./systems/wsl/configuration.nix @@ -232,25 +190,6 @@ }; }; - # Standalone Home Manager Configurations (for Archlinux, etc.) - homeConfigurations = { - # Generic Linux configuration (Archlinux, Ubuntu, Fedora, etc.) - "user@linux" = mkHome { - system = "x86_64-linux"; - modules = [ - ./home/archlinux.nix - ]; - }; - - # ARM64 Linux configuration - "user@linux-arm64" = mkHome { - system = "aarch64-linux"; - modules = [ - ./home/archlinux.nix - ]; - }; - }; - packages.x86_64-linux.bootstrap-wsl = let pkgs = nixpkgs.legacyPackages.x86_64-linux; @@ -268,43 +207,6 @@ program = "${self.packages.x86_64-linux.bootstrap-wsl}/bin/bootstrap-nixos-wsl"; }; - # macOS configurations (keeping your existing setup) - darwinConfigurations = { - # macOS Apple Silicon - "aarch64" = mkDarwin { - system = "aarch64-darwin"; - modules = [ - ./systems/darwin/configuration.nix - home-manager.darwinModules.home-manager - { - home-manager = { - useGlobalPkgs = true; - useUserPackages = true; - users.gaiz = import ./home/darwin.nix; - extraSpecialArgs = { inherit inputs; }; - }; - } - ]; - }; - - # macOS Intel - "x86_64" = mkDarwin { - system = "x86_64-darwin"; - modules = [ - ./systems/darwin/configuration.nix - home-manager.darwinModules.home-manager - { - home-manager = { - useGlobalPkgs = true; - useUserPackages = true; - users.gaiz = import ./home/darwin.nix; - extraSpecialArgs = { inherit inputs; }; - }; - } - ]; - }; - }; - formatter = forAllSystems (system: nixpkgs.legacyPackages.${system}.nixfmt); checks = forAllSystems ( @@ -388,7 +290,7 @@ ]; shellHook = '' echo "Dotfiles development environment" - echo "Use 'nixos-rebuild' or 'home-manager' commands to apply configurations" + echo "Use 'nixos-rebuild' to apply NixOS and Home Manager configurations" ''; }; } diff --git a/git/.config/git/README.md b/git/.config/git/README.md index b1cf506..4ebc3b3 100644 --- a/git/.config/git/README.md +++ b/git/.config/git/README.md @@ -1,62 +1,43 @@ # Git Configuration -This directory contains the shared git configuration that works across all platforms (NixOS, macOS, Linux, WSL). +`config` is shared by NixOS (Home Manager symlink) and macOS/Arch Linux (GNU +Stow). It sets Neovim as the editor, delta as the pager/diff filter, `input` +line-ending conversion, `zdiff3` merge conflicts, and SSH commit signing. +Install Neovim and delta when using it outside NixOS. -## OS-Specific Configurations - -You can create OS-specific git configuration files that will be automatically included: - -### Setup - -Add the following to the bottom of `config`: +The tracked identity is a default. Set your own identity and signing key in +`~/.config/git/config.local`, which is already included **after** the defaults: ```gitconfig -# OS-specific configurations -# These will be loaded if the files exist -[include] - path = ~/.config/git/config.local - path = ~/.config/git/config.darwin - path = ~/.config/git/config.linux - path = ~/.config/git/config.wsl +[user] + name = Your Name + email = you@example.com + signingkey = ~/.ssh/id_ed25519.pub ``` -### Create OS-Specific Files - -Then create the appropriate files: - -- **`config.darwin`** - macOS-specific settings -- **`config.linux`** - Native Linux-specific settings -- **`config.wsl`** - WSL-specific settings -- **`config.local`** - Machine-specific settings (not tracked in git) - -### Example OS-Specific Files +Use an existing SSH signing key or generate one separately; no private keys are +provided. `commit.gpgsign = true` is enabled, so commits require a usable signing +key and private-key/agent access. If signing is not wanted on this machine, +override it explicitly: -**config.darwin:** ```gitconfig -# macOS-specific git configuration - -[core] - # macOS specific settings -``` - -**config.linux:** -```gitconfig -# Linux-specific git configuration - -[core] - # Linux specific settings +[commit] + gpgsign = false ``` -**config.wsl:** -```gitconfig -# WSL-specific git configuration +`git/.config/git/config.local` is ignored by the repository. When the whole +config directory is symlinked, creating the local file writes into the checkout; +keep it untracked. An existing `~/.gitconfig` can override XDG config settings. +Inspect the source of effective settings with: -[core] - # WSL might need different autocrlf handling +```sh +git config --show-origin --list ``` -### Notes +There are no automatic OS-specific includes. Only `config.local` is included. +If you add more include paths yourself, Git reads all existing files at those +paths; names such as `config.darwin` do not cause OS detection. -- Git will silently ignore include paths that don't exist -- Settings in later files override earlier ones -- You can add `config.local` to `.gitignore` for machine-specific settings +`core.excludesfile` points to `.gitignore_global`. The sibling `ignore` file is +not the explicitly selected global ignore file. Lazygit's separate config +also uses delta, with `--paging=never` because Lazygit handles scrolling itself. diff --git a/home/archlinux.nix b/home/archlinux.nix deleted file mode 100644 index 15dc488..0000000 --- a/home/archlinux.nix +++ /dev/null @@ -1,40 +0,0 @@ -{ pkgs, ... }: - -{ - # Import common modules - imports = [ - ./modules/common.nix - ./modules/shell.nix - ./modules/dev-tools.nix - ./modules/git.nix - ./modules/neovim.nix - ./modules/terminal.nix - ./modules/wezterm.nix - ./modules/languages.nix - ]; - - # Archlinux-specific configuration - # Since this is standalone Home Manager (not NixOS), we need to be careful - # about what services and features we enable - - home = { - # User information - IMPORTANT: Change these before deployment - username = "user3301"; - homeDirectory = "/home/user3301"; - - # Additional packages for Archlinux - packages = with pkgs; [ - # Tools that complement Arch packages - # Most system packages will be installed via pacman - # Use Nix for development tools and user applications - - # Example: Nix-specific or bleeding-edge tools - ]; - - # Home Manager state version - stateVersion = "25.05"; - }; - - # Targets for non-NixOS systems - targets.genericLinux.enable = true; -} diff --git a/home/darwin.nix b/home/darwin.nix deleted file mode 100644 index 10fcca5..0000000 --- a/home/darwin.nix +++ /dev/null @@ -1,39 +0,0 @@ -{ - config, - pkgs, - ... -}: - -{ - # Import common modules - imports = [ - ./modules/common.nix - ./modules/shell.nix - ./modules/dev-tools.nix - ./modules/git.nix - ./modules/neovim.nix - ./modules/terminal.nix - ./modules/wezterm.nix - ./modules/languages.nix - ]; - - home = { - # User information - username = "gaiz"; - homeDirectory = "/Users/gaiz"; - - # macOS-specific packages - packages = with pkgs; [ - # macOS-specific tools - # Note: GUI apps installed via Homebrew (see Brewfile) - ]; - - # Home Manager state version - stateVersion = "24.05"; - }; - - # Aerospace window manager config - xdg.configFile."aerospace".source = - config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/dotfiles/aerospace/.config/aerospace"; - -} diff --git a/home/modules/common.nix b/home/modules/common.nix index bbac733..1070f0b 100644 --- a/home/modules/common.nix +++ b/home/modules/common.nix @@ -1,7 +1,7 @@ { config, pkgs, ... }: { - # Common configuration shared across all platforms + # Common configuration shared by the NixOS homes # Let Home Manager manage itself programs.home-manager.enable = true; diff --git a/home/modules/wezterm.nix b/home/modules/wezterm.nix index 6efac0e..4f48e63 100644 --- a/home/modules/wezterm.nix +++ b/home/modules/wezterm.nix @@ -2,7 +2,7 @@ { # Wezterm terminal emulator - # Note: Wezterm is installed via Homebrew on macOS, via Nix on Linux + # Wezterm is installed in home/nixos-native.nix. # Not used on WSL (terminal emulator runs on the Windows host). xdg.configFile."wezterm".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/dotfiles/wezterm/.config/wezterm"; diff --git a/nvim/.config/nvim/README.md b/nvim/.config/nvim/README.md index 185280b..2a0c43d 100644 --- a/nvim/.config/nvim/README.md +++ b/nvim/.config/nvim/README.md @@ -1,4 +1,55 @@ -# 💤 LazyVim +# Neovim Configuration -A starter template for [LazyVim](https://github.com/LazyVim/LazyVim). -Refer to the [documentation](https://lazyvim.github.io/installation) to get started. +This is a customized [LazyVim](https://www.lazyvim.org/) configuration, not an +unmodified starter. `init.lua` loads `lua/config/lazy.lua`, which bootstraps +lazy.nvim using Git and imports LazyVim plus `lua/plugins/`. + +NixOS links this directory through Home Manager. On macOS and Arch Linux, +install Neovim and its dependencies with the native package manager, then run +`stow --target="$HOME" nvim` from `~/dotfiles`. Stow does not install Neovim. + +## Plugins and UI + +`lazyvim.json` enables Copilot Chat, mini-surround, debugging and testing +support, and .NET, Go, and Python extras. Additional plugin configuration +selects Catppuccin Frappe, customizes Markdown rendering and the Snacks +dashboard/picker, and adds smear-cursor and Roslyn support. Relative line +numbers are disabled; folding uses Tree-sitter. + +Plugins are installed by lazy.nvim on first launch and pinned separately in +`lazy-lock.json`. Network access and Git are needed for installation. Use +`:Lazy` to manage plugins and `:checkhealth` to diagnose missing dependencies. +Review lockfile changes after plugin updates. Copilot authentication is a +separate manual step. + +## Language servers + +`lua/plugins/lsp.lua` detects NixOS via `/etc/NIXOS` or `/etc/nixos`. +For the explicitly configured Lua, TypeScript/web, Python (Pyright), Rust, and +Go servers, Mason management is disabled on NixOS and enabled elsewhere. +NixOS installs servers, formatters, compiler tools, and fswatch through +`home/modules/neovim.nix`. + +The Nix server `nil` always has Mason management disabled; provide it on `PATH` +yourself outside NixOS if you edit Nix files. Native package manifests do not +install all language runtimes, servers, or formatters. Mason-managed tools may +also need Node.js, Python, Go, or other runtime/build dependencies. + +For C#, OmniSharp is disabled in favor of `seblyng/roslyn.nvim`. On NixOS, +`roslyn-ls` supplies `Microsoft.CodeAnalysis.LanguageServer` on `PATH`. +Elsewhere, the additional Crashdummyy Mason registry allows: + +```vim +:MasonInstall roslyn +``` + +Roslyn enables Neovim file watching; install `fswatch` outside NixOS as needed. +The C# formatter override clears CSharpier so LSP formatting can be used. + +Python configuration looks for `venv`, `.venv`, and `.virtualenv`: Pyright uses +a discovered Python interpreter, while pylsp can use a virtualenv's `pylsp` +executable. Its Ruff plugin settings require that plugin to be installed in +the chosen environment. + +See [LazyVim's installation requirements](https://www.lazyvim.org/installation) +for current Neovim, compiler, and external-tool requirements. diff --git a/nvim/.config/nvim/lua/plugins/conform.lua b/nvim/.config/nvim/lua/plugins/conform.lua index 2c53c72..1904077 100644 --- a/nvim/.config/nvim/lua/plugins/conform.lua +++ b/nvim/.config/nvim/lua/plugins/conform.lua @@ -1,7 +1,7 @@ return { "stevearc/conform.nvim", opts = function(_, opts) - -- Disable csharpier for C#; fall back to omnisharp's LSP formatting + -- Disable csharpier for C#; fall back to Roslyn's LSP formatting -- (lsp_format = "fallback"), which honors .editorconfig. opts.formatters_by_ft = opts.formatters_by_ft or {} opts.formatters_by_ft.cs = {} diff --git a/systems/darwin/configuration.nix b/systems/darwin/configuration.nix deleted file mode 100644 index 05efcae..0000000 --- a/systems/darwin/configuration.nix +++ /dev/null @@ -1,78 +0,0 @@ -{ pkgs, ... }: - -{ - # System configuration for macOS using nix-darwin - - # Nix settings - nix = { - settings = { - experimental-features = [ - "nix-command" - "flakes" - ]; - auto-optimise-store = true; - }; - - # Garbage collection - gc = { - automatic = true; - interval = { - Weekday = 0; - Hour = 0; - Minute = 0; - }; - options = "--delete-older-than 7d"; - }; - }; - - # Allow unfree packages - nixpkgs.config.allowUnfree = true; - - # System packages (minimal, most packages go in Home Manager) - environment.systemPackages = with pkgs; [ - vim - git - ]; - - # Programs - programs.zsh.enable = true; - - system = { - stateVersion = 4; - - # macOS system defaults - defaults = { - dock = { - autohide = true; - orientation = "bottom"; - show-recents = false; - tilesize = 48; - }; - - finder = { - AppleShowAllExtensions = true; - ShowPathbar = true; - FXEnableExtensionChangeWarning = false; - }; - - NSGlobalDomain = { - AppleShowAllExtensions = true; - InitialKeyRepeat = 15; - KeyRepeat = 2; - }; - }; - }; - - # Fonts - fonts.packages = with pkgs; [ - (nerdfonts.override { - fonts = [ - "JetBrainsMono" - "FiraCode" - ]; - }) - ]; - - # Services - services.nix-daemon.enable = true; -} diff --git a/systems/native/configuration.nix b/systems/native/configuration.nix index 373ab6e..a7776fe 100644 --- a/systems/native/configuration.nix +++ b/systems/native/configuration.nix @@ -4,7 +4,7 @@ }: { - # Import hardware configuration (will be generated on the target machine) + # Replace this VirtualBox configuration with the target machine's hardware config. imports = [ ../hardware/hardware-vb.nix ]; # Boot loader configuration @@ -27,7 +27,7 @@ }; # System configuration - system.stateVersion = "25.11"; # Update to match your NixOS version + system.stateVersion = "25.11"; # Compatibility defaults, not the package release # Nix settings nix = { diff --git a/systems/wsl/configuration.nix b/systems/wsl/configuration.nix index e03179e..309f0c5 100644 --- a/systems/wsl/configuration.nix +++ b/systems/wsl/configuration.nix @@ -15,7 +15,7 @@ }; # System configuration - system.stateVersion = "25.05"; # Update to match your NixOS version + system.stateVersion = "25.05"; # Compatibility defaults, not the package release # Nix settings nix = {