macos-zsh-customization

name	macos-zsh-customization
category	macos
description	Customize oh-my-zsh (OMZ) on macOS — install plugins, edit themes, modify .zshrc. Covers pitfalls with protected files and special character escaping.

macOS zsh/oh-my-zsh Customization

File Edit Pitfalls

.zshrc is protected

The patch tool cannot write to ~/.zshrc — it's classified as a protected system/credential file ("Write denied").

Use sed -i '' instead:

sed -i '' 's/old_pattern/new_pattern/' ~/.zshrc

Theme files have tricky characters

OMZ theme files (e.g., ~/.oh-my-zsh/themes/robbyrussell.zsh-theme) contain $, %, {, } — sed escaping is error-prone.

Use Python heredoc instead of sed for theme files:

python3 << 'EOF'
path = '$HOME/.oh-my-zsh/themes/<theme-name>.zsh-theme'
with open(path, 'r') as f:
    content = f.read()
content = content.replace('old_text', 'new_text')
with open(path, 'w') as f:
    f.write(content)
EOF

Common Operations

Install a plugin

git clone https://github.com/<repo> ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/<name>
# Then edit .zshrc with sed:
sed -i '' 's/^plugins=(\(.*\))/plugins=(\1 <name>)/' ~/.zshrc

Add hostname to prompt (robbyrussell theme)

python3 << 'EOF'
path = '$HOME/.oh-my-zsh/themes/robbyrussell.zsh-theme'
with open(path, 'r') as f:
    content = f.read()
content = content.replace('%{$fg[cyan]%}%c', '%{$fg[cyan]%}%m %{$fg[cyan]}%c')
with open(path, 'w') as f:
    f.write(content)
EOF

Pitfall: %1{...%} is broken zsh syntax

Some OMZ theme versions use %1{emoji%} (e.g., %1{➜%}) which zsh doesn't recognize. It treats the closing %} as a literal }, causing stray } in the prompt like ➜ M2 }~.

Fix: Remove %1{ wrapper, use just the emoji directly:

# BROKEN — causes stray } in prompt:
PROMPT="%(?:%{$fg_bold[green]%}%1{➜%} ...)"

# CORRECT:
PROMPT="%(?:%{$fg_bold[green]%}➜ ...)"

Also fix %1{✗%} → ✗ in ZSH_THEME_GIT_PROMPT_DIRTY.

Key zsh prompt escapes

Escape	Meaning
%m	Short hostname
%M	Full hostname
%n	Username
%~	Current dir (abbreviated)
%c	Trailing dir component
%(?:green:red)	Conditional (success:fail)