# Usage Guide

This guide provides detailed instructions for using and maintaining your Nix Home Manager configuration.

## Table of Contents

1. [Initial Setup on a New Machine](#initial-setup-on-a-new-machine)
2. [Switching Between Profiles](#switching-between-profiles)
3. [Adding New Packages](#adding-new-packages)
4. [Adding New Configuration Modules](#adding-new-configuration-modules)
5. [Updating Flake Inputs](#updating-flake-inputs)
6. [Day-to-Day Operations](#day-to-day-operations)
7. [Troubleshooting](#troubleshooting)

---

## Initial Setup on a New Machine

### Step 1: Install Nix

```bash
# Install Nix with the official installer
curl -L https://nixos.org/nix/install | sh

# Follow the prompts and restart your terminal
# Or source the nix profile manually:
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
```

### Step 2: Enable Flakes

Flakes are an experimental feature that needs to be enabled:

```bash
mkdir -p ~/.config/nix
cat >> ~/.config/nix/nix.conf << EOF
experimental-features = nix-command flakes
EOF
```

### Step 3: Install Homebrew (macOS only)

Homebrew is required for GUI applications:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to PATH (for Apple Silicon Macs)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

### Step 4: Install 1Password and Configure SSH Agent

1. Download and install [1Password](https://1password.com/downloads/mac/)
2. Sign in to your 1Password account
3. Enable SSH Agent:
   - Open 1Password → Settings → Developer
   - Enable "SSH Agent"
   - Enable "Use the SSH agent"
4. Enable CLI integration:
   - In the same Developer settings
   - Enable "Integrate with 1Password CLI"

### Step 5: Clone the Repository

```bash
# Clone to ~/.dotfiles (recommended location)
git clone <repository-url> ~/.dotfiles
cd ~/.dotfiles
```

### Step 6: Build and Apply Configuration

For a **personal machine**:

```bash
# First-time build (creates darwin-rebuild command)
nix build .#darwinConfigurations.personal.system

# Apply the configuration
./result/sw/bin/darwin-rebuild switch --flake .#personal
```

For a **work machine**:

```bash
# First-time build
nix build .#darwinConfigurations.work.system

# Apply the configuration
./result/sw/bin/darwin-rebuild switch --flake .#work
```

### Step 7: Restart Your Shell

```bash
# Start a new shell to pick up all changes
exec zsh
```

### Step 8: Verify Installation

```bash
# Check that key tools are available
which starship    # Should show nix store path
which atuin       # Should show nix store path
which nvim        # Should show nix store path

# Verify git configuration
git config --get user.email
git config --get user.signingkey
```

---

## Switching Between Profiles

### Switching from Personal to Work

If you need to reconfigure a machine from personal to work:

```bash
cd ~/.dotfiles
darwin-rebuild switch --flake .#work
```

**Note:** This will:
- Change git configuration (email, signing key)
- Update SSH hosts
- Remove personal-only Homebrew casks
- Disable personal-only features (like jellyfin-tui)

### Switching from Work to Personal

```bash
cd ~/.dotfiles
darwin-rebuild switch --flake .#personal
```

**Note:** This will:
- Change git configuration to personal settings
- Update SSH hosts
- Install personal Homebrew casks (darktable, signal, proton-*, steam)
- Enable personal features

### Temporary Profile Testing

To test a profile without fully switching:

```bash
# Build without applying
darwin-rebuild build --flake .#work

# Inspect what would change
ls -la result/
```

---

## Adding New Packages

### Adding CLI Tools via Nix (Recommended)

Edit [`modules/home/packages.nix`](../modules/home/packages.nix):

```nix
home.packages = with pkgs; [
  # ... existing packages ...
  
  # Add your new package
  your-new-package
];
```

Then rebuild:

```bash
darwin-rebuild switch --flake .#personal  # or .#work
```

#### Finding Package Names

```bash
# Search for packages
nix search nixpkgs your-package-name

# Or use the online search
# https://search.nixos.org/packages
```

### Adding GUI Applications via Homebrew

Edit [`modules/darwin/homebrew.nix`](../modules/darwin/homebrew.nix):

#### For All Machines (Shared)

```nix
casks = {
  shared = [
    # ... existing casks ...
    "your-new-app"
  ];
};
```

#### For Personal Machine Only

```nix
casks = {
  personal = [
    # ... existing personal casks ...
    "personal-only-app"
  ];
};
```

Then rebuild:

```bash
darwin-rebuild switch --flake .#personal
```

### Adding Homebrew Formulae (Non-Nix CLI tools)

For CLI tools that must come from Homebrew (e.g., from custom taps):

```nix
# In modules/darwin/homebrew.nix
brews = [
  # ... existing brews ...
  "tap-name/formula-name"
];
```

### Adding Homebrew Taps

```nix
# In modules/darwin/homebrew.nix
taps = [
  # ... existing taps ...
  "owner/repo"
];
```

---

## Adding New Configuration Modules

### Creating a New Home Manager Module

1. Create a new file in `modules/home/`:

```bash
touch modules/home/your-module.nix
```

2. Add the module structure:

```nix
# modules/home/your-module.nix
{ config, pkgs, lib, ... }:

with lib;

let
  cfg = config.modules.yourModule;
in {
  options.modules.yourModule = {
    enable = mkEnableOption "Your module description";
    
    # Add your options here
    someSetting = mkOption {
      type = types.str;
      default = "default-value";
      description = "Description of this setting";
    };
  };

  config = mkIf cfg.enable {
    # Your configuration here
    programs.someProgram = {
      enable = true;
      # ...
    };
  };
}
```

3. Import the module in [`home/default.nix`](../home/default.nix):

```nix
imports = [
  # ... existing imports ...
  ../modules/home/your-module.nix
];
```

4. Enable the module:

```nix
# In home/default.nix or profile-specific file
modules.yourModule = {
  enable = true;
  someSetting = "custom-value";
};
```

### Creating Profile-Specific Configuration

For settings that differ between personal and work:

1. Add options to your module with sensible defaults
2. Override in profile files:

```nix
# home/personal.nix
modules.yourModule = {
  enable = true;
  someSetting = "personal-value";
};

# home/work.nix
modules.yourModule = {
  enable = true;
  someSetting = "work-value";
};
```

### Adding Application Configuration Files

For apps without Home Manager modules, use `home.file`:

```nix
# In modules/home/apps.nix or a new module
home.file = {
  ".config/your-app/config.toml".text = ''
    # Your config content
    setting = "value"
  '';
  
  # Or copy from a file
  ".config/your-app/config.toml".source = ./files/your-app-config.toml;
};
```

---

## Updating Flake Inputs

### Update All Inputs

```bash
cd ~/.dotfiles

# Update all inputs to their latest versions
nix flake update

# Review changes
git diff flake.lock

# Apply the updates
darwin-rebuild switch --flake .#personal
```

### Update Specific Input

```bash
# Update only nixpkgs
nix flake lock --update-input nixpkgs

# Update only home-manager
nix flake lock --update-input home-manager

# Update only nix-darwin
nix flake lock --update-input nix-darwin
```

### Pin to Specific Version

Edit `flake.nix` to pin an input:

```nix
inputs = {
  # Pin to specific commit
  nixpkgs.url = "github:nixos/nixpkgs/abc123...";
  
  # Pin to specific branch
  nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
};
```

### Check for Updates

```bash
# Show current input versions
nix flake metadata

# Show what would be updated
nix flake update --dry-run
```

---

## Day-to-Day Operations

### Rebuilding After Changes

```bash
cd ~/.dotfiles

# Make your changes to .nix files
vim modules/home/packages.nix

# Rebuild and switch
darwin-rebuild switch --flake .#personal
```

### Quick Rebuild Alias

Add to your shell configuration or use directly:

```bash
# Alias for quick rebuilds
alias rebuild="darwin-rebuild switch --flake ~/.dotfiles#personal"
alias rebuild-work="darwin-rebuild switch --flake ~/.dotfiles#work"
```

### Checking Configuration Validity

```bash
# Validate the flake
nix flake check

# Build without switching (dry run)
darwin-rebuild build --flake .#personal
```

### Viewing Generation History

```bash
# List all generations
darwin-rebuild --list-generations

# See what's in the current generation
ls -la /run/current-system
```

### Rolling Back

```bash
# Rollback to previous generation
darwin-rebuild --rollback

# Switch to specific generation
darwin-rebuild switch --generation 42
```

### Garbage Collection

```bash
# Remove old generations (keeps current)
nix-collect-garbage

# Remove all old generations
nix-collect-garbage -d

# Remove generations older than 30 days
nix-collect-garbage --delete-older-than 30d
```

### Development Shell

For working on this repository:

```bash
cd ~/.dotfiles

# Enter development shell with formatting tools
nix develop

# Format all Nix files
nixfmt **/*.nix
```

---

## Troubleshooting

### Common Issues

#### "experimental-features" Error

**Problem:** `error: experimental Nix feature 'flakes' is disabled`

**Solution:**
```bash
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```

#### Homebrew Cask Installation Fails

**Problem:** A cask fails to install during rebuild

**Solution:**
```bash
# Update Homebrew
brew update

# Check for issues
brew doctor

# Try installing manually first
brew install --cask problematic-cask

# Then rebuild
darwin-rebuild switch --flake .#personal
```

#### SSH Key Not Found

**Problem:** Git operations fail with SSH key errors

**Solution:**
1. Ensure 1Password SSH agent is enabled
2. Check the key is in 1Password
3. Verify the public key file exists:
   ```bash
   ls -la ~/.ssh/keys/
   ```
4. Test SSH connection:
   ```bash
   ssh -T git@github.com
   ```

#### Build Fails with "attribute not found"

**Problem:** `error: attribute 'somePackage' missing`

**Solution:**
```bash
# Update flake inputs
nix flake update

# Search for correct package name
nix search nixpkgs package-name
```

#### Conflicting Files

**Problem:** `error: collision between ... and ...`

**Solution:**
1. Check if the file is managed by multiple sources
2. Remove manual file if it exists:
   ```bash
   rm ~/.config/conflicting-file
   ```
3. Rebuild

### Debug Mode

For detailed error information:

```bash
# Build with trace
darwin-rebuild switch --flake .#personal --show-trace

# Even more verbose
darwin-rebuild switch --flake .#personal --show-trace --verbose
```

### Interactive Debugging

```bash
# Open Nix REPL with flake loaded
nix repl
:lf .
# Now you can inspect the configuration
darwinConfigurations.personal.config.home-manager.users.alice.home.packages
```

### Reset to Clean State

If things are badly broken:

```bash
# Remove result symlink
rm -f result

# Clean Nix store
nix-collect-garbage -d

# Remove home-manager generations
rm -rf ~/.local/state/home-manager

# Rebuild from scratch
nix build .#darwinConfigurations.personal.system
./result/sw/bin/darwin-rebuild switch --flake .#personal
```

### Getting Help

```bash
# Home Manager options
man home-configuration.nix

# nix-darwin options
man darwin-configuration.nix

# Search for options online
# https://home-manager-options.extranix.com/
# https://daiderd.com/nix-darwin/manual/
```

---

## Best Practices

1. **Commit changes before rebuilding** - Makes it easy to rollback
2. **Test builds before switching** - Use `darwin-rebuild build` first
3. **Update inputs regularly** - Keep packages up to date
4. **Use garbage collection** - Prevent disk space issues
5. **Document custom modules** - Add comments explaining purpose
6. **Keep secrets out of Nix** - Use 1Password or sops-nix for secrets