# ZSH Configuration

A modular ZSH configuration designed to be portable, easy to maintain, and friendly to both Linux and macOS.

The main idea is simple: keep the top-level shell startup files small, then split aliases, functions, exports, prompt setup, keybindings, and OS-specific behavior into separate files.

## Layout

| File | Purpose |
|---|---|
| `zshrc` | Main interactive shell configuration. Sources the modular config files. |
| `zprofile` | Login shell configuration. Sources `zshrc` where appropriate. |
| `aliases.zsh` | Shell aliases. |
| `functions.zsh` | Utility function definitions. |
| `exports.zsh` | Cross-platform environment variables and PATH setup. |
| `initializations.zsh` | Tool initialization code, such as language managers or runtime setup. |
| `keybinds.zsh` | Custom ZSH keybindings. |
| `ps1.zsh` | Prompt configuration. |
| `macrc` | macOS-specific configuration, especially Homebrew paths and macOS-only tools. |
| `scripts/` | Helper scripts used by this configuration. |

## Installation

Clone the repository:

```sh
git clone git.xchg.sh:angrygoats/zsh-v2.git ~/zsh-v2
```

Back up any existing ZSH files:

```sh
mv ~/.zshrc ~/.zshrc.backup 2>/dev/null || true
mv ~/.zprofile ~/.zprofile.backup 2>/dev/null || true
```

Symlink the main files:

```sh
ln -s ~/zsh-v2/zshrc ~/.zshrc
ln -s ~/zsh-v2/zprofile ~/.zprofile
```

Reload your shell:

```sh
source ~/.zshrc
```

## Private Configuration

Private or machine-local values should not be committed to this repository.

The following files are automatically sourced if present:

```text
$HOME/.bash_private
$HOME/.private
$HOME/.zsh_private
```

Use these for secrets, tokens, private exports, work-specific paths, or anything machine-specific that should not live in Git.

## OS-Specific Configuration

macOS-specific configuration belongs in:

```text
$HOME/.macrc
```

This is the right place for Homebrew paths, macOS-only tools, GUI application CLI paths, and Apple Silicon versus Intel Homebrew differences.

Linux-specific configuration can be placed in a Linux-specific file if needed.

## PATH Management

This configuration uses ZSH’s `path` array where possible instead of repeatedly prepending strings to `$PATH`.

At the end of shell initialization, PATH entries should be deduplicated with:

```zsh
typeset -U path PATH
```

This keeps path ordering predictable while avoiding duplicate entries.

## Git Completion

Git completion support is installed automatically on first run into:

```text
$HOME/.zsh
```

The setup downloads:

```text
git-completion.bash
_git
```

from the official Git repository.

If the download fails, manually place both completion files in `$HOME/.zsh` and reload the shell.

## Syntax Highlighting

If the installed ZSH version is new enough, `zsh-syntax-highlighting` is automatically cloned into:

```text
$HOME/.zsh/zsh-syntax-highlighting
```

It is sourced last, which is required for `zsh-syntax-highlighting` to work correctly with most ZSH configurations.

## Rust

Rust is initialized from:

```text
$HOME/.cargo/env
```

if that file exists.

This exposes standard Rust tooling such as:

```text
cargo
rustc
rustfmt
clippy
rust-analyzer
```

when installed through `rustup`.

## Go

If Go is installed, this configuration sets:

```zsh
GOPATH=$HOME/.go
```

and adds the Go binary directory to `PATH`.

## macOS Notes

On macOS, machine-specific Homebrew setup should live in `macrc`, not in the shared cross-platform exports file.

Common macOS tools configured there include:

```text
Homebrew
LLVM / clangd / clang-format
OpenSSL
OpenJDK
Qt
Tcl/Tk
Ghostty
Sublime Text CLI
```

The Sublime Text CLI symlink should be created once per machine, not on every shell startup:

```sh
sudo mkdir -p /usr/local/bin
sudo ln -sf "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl
```

## Design Goals

This configuration aims to be:

- Modular
- Portable across Linux and macOS
- Safe to version-control
- Friendly to private machine-local overrides
- Predictable about `PATH` ordering
- Minimal enough to debug when something goes wrong