home/README.md

# Nix Home Manager Dotfiles

A declarative, reproducible dotfiles configuration using [Nix](https://nixos.org/), [nix-darwin](https://github.com/LnL7/nix-darwin), and [Home Manager](https://github.com/nix-community/home-manager). This setup supports two profiles: **personal** and **work**, allowing different configurations for different machines while sharing common settings.

## Overview

This repository manages:

- **Shell environment**: Zsh with Starship prompt, Atuin history, Zoxide navigation, FZF fuzzy finder
- **Development tools**: Neovim, Tmux, Git with delta, lazygit
- **CLI utilities**: Modern replacements (eza, bat, ripgrep, fd, delta)
- **Container tools**: Docker, Colima, Kubernetes (kubectl, helm, k9s)
- **macOS applications**: Managed via Homebrew casks through nix-darwin
- **SSH configuration**: 1Password SSH agent integration with profile-specific hosts
- **Git configuration**: Profile-specific signing keys and project-based configs

## Prerequisites

### 1. Install Nix

Install Nix with flakes support:

```bash
# Install Nix (multi-user installation recommended for macOS)
curl -L https://nixos.org/nix/install | sh

# Restart your shell or source the nix profile
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
```

### 2. Enable Flakes

Create or edit `~/.config/nix/nix.conf`:

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

### 3. Install Homebrew (macOS)

Homebrew is required for GUI applications (casks):

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

### 4. Install 1Password

This configuration uses 1Password for SSH key management. Install 1Password and enable:
- **SSH Agent**: Settings → Developer → SSH Agent
- **CLI Integration**: Settings → Developer → Command-Line Interface (CLI)

## Quick Start

### Personal Machine Setup

```bash
# Clone the repository
git clone <repository-url> ~/.dotfiles
cd ~/.dotfiles

# Build and activate the personal configuration
make switch-personal
```

### Work Machine Setup

```bash
# Clone the repository
git clone <repository-url> ~/.dotfiles
cd ~/.dotfiles

# Build and activate the work configuration
make switch-work
```

## Makefile Commands

The project includes a Makefile for convenient operations. Run `make help` to see all available commands.

### Testing/Validation

| Command | Description |
|---------|-------------|
| `make check` | Run nix flake check to validate the flake |
| `make show` | Display the flake outputs |
| `make dry-run-personal` | Dry-run build for personal configuration |
| `make dry-run-work` | Dry-run build for work configuration |

### Building/Applying

| Command | Description |
|---------|-------------|
| `make switch-personal` | Apply personal configuration with darwin-rebuild |
| `make switch-work` | Apply work configuration with darwin-rebuild |
| `make build-personal` | Build personal configuration without switching |
| `make build-work` | Build work configuration without switching |

### Maintenance

| Command | Description |
|---------|-------------|
| `make update` | Update all flake inputs |
| `make update-nixpkgs` | Update only nixpkgs input |
| `make gc` | Run garbage collection to free disk space |
| `make gc-old` | Delete old generations and run garbage collection |

### Development

| Command | Description |
|---------|-------------|
| `make fmt` | Format all Nix files using nixfmt |
| `make lint` | Run statix linter on Nix files |

## Project Structure

```
.
├── flake.nix                    # Main flake entry point
├── flake.lock                   # Locked dependency versions
├── Makefile                     # Convenient make targets
├── README.md                    # This file
│
├── home/                        # Home Manager configurations
│   ├── default.nix              # Shared home configuration
│   ├── personal.nix             # Personal profile overrides
│   └── work.nix                 # Work profile overrides
│
├── hosts/                       # Machine-specific nix-darwin configs
│   ├── personal/
│   │   └── default.nix          # Personal machine darwin settings
│   └── work/
│       └── default.nix          # Work machine darwin settings
│
├── modules/                     # Reusable Nix modules
│   ├── darwin/
│   │   └── homebrew.nix         # Homebrew cask management
│   │
│   └── home/                    # Home Manager modules
│       ├── apps.nix             # Application configs (aerospace, jellyfin-tui)
│       ├── git.nix              # Git configuration
│       ├── git-files.nix        # Project-specific git configs
│       ├── packages.nix         # CLI packages via Nix
│       ├── shell.nix            # Shell environment (zsh, starship, etc.)
│       ├── ssh.nix              # SSH configuration
│       └── tmux.nix             # Tmux configuration
│
└── docs/                        # Documentation
    ├── migration-analysis.md    # Original migration analysis
    ├── nix-architecture.md      # Architecture design
    └── usage.md                 # Detailed usage guide
```

## Customization

### Adding New Packages

#### Via Nix (Preferred for CLI tools)

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

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

#### Via Homebrew (For GUI apps/casks)

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

```nix
casks = {
  shared = [
    # Add casks for all machines
    "your-app"
  ];
  personal = [
    # Add casks for personal machine only
    "personal-only-app"
  ];
};
```

### Modifying Shell Configuration

Edit [`modules/home/shell.nix`](modules/home/shell.nix:1) to customize:
- Shell aliases
- Environment variables
- Zsh settings
- Starship prompt
- Atuin history settings

### Modifying Git Configuration

Edit [`modules/home/git.nix`](modules/home/git.nix:1) for global settings, or the profile files:
- [`home/personal.nix`](home/personal.nix:20) - Personal git settings
- [`home/work.nix`](home/work.nix:23) - Work git settings

### Adding SSH Hosts

Edit [`modules/home/ssh.nix`](modules/home/ssh.nix:83) to add new SSH host configurations.

## Profile Differences

| Feature | Personal | Work |
|---------|----------|------|
| **Git Email** | Personal email | Work email |
| **Git Signing Key** | Personal SSH key | Work SSH key |
| **SSH Hosts** | github-private, gitea | github-private, github-zeronorth, coder |
| **Homebrew Casks** | All + personal apps | Shared apps only |
| **Personal Apps** | darktable, signal, proton-*, steam | - |
| **Jellyfin TUI** | Enabled | Disabled |

## Troubleshooting

### Build Errors

```bash
# Check flake validity
make check

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

### Rollback

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

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

### Clean Rebuild

```bash
# Remove result symlink and rebuild
rm -f result
make gc
make switch-personal
```

### Homebrew Issues

```bash
# If Homebrew packages fail to install
brew update
brew doctor
make switch-personal
```

## Documentation

- [`docs/usage.md`](docs/usage.md) - Detailed usage guide
- [`docs/nix-architecture.md`](docs/nix-architecture.md) - Architecture design and module documentation
- [`docs/migration-analysis.md`](docs/migration-analysis.md) - Original migration analysis

## License

This is a personal dotfiles repository. Feel free to use it as inspiration for your own configuration.