# Shell Module Configuration

## Alias Pattern

Shell aliases are managed through two mechanisms:

### 1. Nix Module Aliases (`environment.shellAliases`)

Global aliases that apply system-wide go in nix modules:

```nix
# modules/shell/zsh/default.nix
environment.shellAliases = {
  cd = "z";
  ls = "eza --group-directories-first --git";
};

# modules/editors/vim.nix
environment.shellAliases = {
  vim = "nvim";
  v = "nvim";
};
```

These are written to `/etc/zshrc` by nix-darwin/NixOS.

### 2. Config-Specific Aliases (`config/<tool>/aliases.zsh`)

Tool-specific aliases and functions go in their own files:

- `config/jj/aliases.zsh` - Jujutsu VCS aliases
- `config/zsh/aliases.zsh` - General zsh aliases and functions
- `config/claude/aliases.zsh` - Claude Code aliases (module now in modules/agents/claude/)

These are sourced by `.zshrc` or via `modules.shell.zsh.rcFiles`.

## ZSH Configuration Structure

The zsh module uses recursive linking for `config/zsh/`:

```nix
home.configFile."zsh" = {
  source = "${configDir}/zsh";
  recursive = true;
};
```

This allows:

- Nix-managed files from `config/zsh/` to be symlinked
- User to add local files like `~/.config/zsh/local.zshrc`

### Key Files

| File           | Purpose                                    |
| -------------- | ------------------------------------------ |
| `.zshrc`       | Main zsh config, sources other files       |
| `.zshenv`      | Environment setup (runs for all shells)    |
| `extra.zshrc`  | Auto-generated by nix (rcInit + rcFiles)   |
| `extra.zshenv` | Auto-generated by nix (envInit + envFiles) |
| `local.zshrc`  | Host-specific config (not managed by nix)  |
| `aliases.zsh`  | General aliases and functions              |

### Module Options

```nix
modules.shell.zsh = {
  enable = true;
  rcInit = "...";      # Lines added to extra.zshrc
  envInit = "...";     # Lines added to extra.zshenv
  rcFiles = [ ... ];   # Files sourced in extra.zshrc
  envFiles = [ ... ];  # Files sourced in extra.zshenv
};
```

## Adding Aliases

**For a new tool/module:**

1. Create `config/<tool>/aliases.zsh` with tool-specific aliases
2. Source it in the module via `rcFiles` or in `.zshrc`

**For global aliases:**

1. Add to `environment.shellAliases` in the appropriate nix module
