zsh-v2/README.md

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:

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

Back up any existing ZSH files:

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

Symlink the main files:

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

Reload your shell:

source ~/.zshrc

Private Configuration

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

The following files are automatically sourced if present:

$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:

$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:

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:

$HOME/.zsh

The setup downloads:

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:

$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:

$HOME/.cargo/env

if that file exists.

This exposes standard Rust tooling such as:

cargo
rustc
rustfmt
clippy
rust-analyzer

when installed through rustup.

Go

If Go is installed, this configuration sets:

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:

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:

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