macOS Developer Environment Setup

A production-ready development environment for macOS, designed around keyboard-driven workflows, reproducible setup via Ansible, and modern CLI tools that replace legacy UNIX utilities. This configuration separates work and personal contexts at the Git, SSH, and directory levels. Optimized for Apple Silicon with sub-100ms shell startup.

Abstract

The setup centers on three principles:

1. Declarative automation: An Ansible playbook installs all tools and symlinks all configuration files—a fresh machine reaches full productivity in one command.
2. Context separation: Git config uses includeIf to load different identities based on repo path (~/work/ vs ~/personal/). SSH config maps hosts to identity files.
3. Modern CLI replacements: eza > ls, bat > cat, ripgrep > grep, fzf for fuzzy search, zoxide for directory jumping—each is faster and more ergonomic than its predecessor.

The configuration assumes macOS with Apple Silicon (M1/M2/M3/M4). Paths reference /opt/homebrew; Intel Macs use /usr/local.

Shell Configuration

The .zshrc is organized into numbered sections that load in dependency order. The design ensures version managers initialize before tools that depend on them, and plugins that modify the prompt load last. Target startup time: under 100ms.

PATH and Homebrew

8 collapsed lines
1
########################################
2
# ~/.zshrc - Sujeet's shell configuration
3
########################################
4

5
########################################
6
# 0. Early environment / Homebrew setup
7
########################################
8

9
# Static Homebrew paths (faster than eval "$(brew shellenv)")
10
export HOMEBREW_PREFIX="/opt/homebrew"
11
export HOMEBREW_CELLAR="/opt/homebrew/Cellar"
12
export HOMEBREW_REPOSITORY="/opt/homebrew"
13

14
export PATH="$HOME/.local/bin:$PATH"
15
export PATH="$HOMEBREW_PREFIX/bin:$HOMEBREW_PREFIX/sbin:$PATH"
16
export FPATH="$HOMEBREW_PREFIX/share/zsh/site-functions:$FPATH"

Why static paths over brew shellenv: The eval "$(brew shellenv)" call spawns a subprocess (~50-400ms). Since Homebrew paths are constant on Apple Silicon (/opt/homebrew), hardcoding them saves startup time. Intel Macs use /usr/local instead.

Version Managers

The config supports four language ecosystems via dedicated version managers:

3 collapsed lines
1
# --- Go (goenv) ---
2
export GOENV_ROOT="$HOME/.goenv"
3
export PATH="$GOENV_ROOT/bin:$PATH"
4
if command -v goenv &>/dev/null; then
5
  eval "$(goenv init -)"
6
fi
7

3 collapsed lines
8
# --- Python (pyenv) ---
9
export PYENV_ROOT="$HOME/.pyenv"
10
export PATH="$PYENV_ROOT/bin:$PATH"
11
if command -v pyenv &>/dev/null; then
12
  eval "$(pyenv init -)"
13
fi
14

3 collapsed lines
15
# --- Java (SDKMAN) ---
16
export SDKMAN_DIR="$HOME/.sdkman"
17
if [ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ]; then
18
  source "$SDKMAN_DIR/bin/sdkman-init.sh"
19
fi
20

21
# --- Node.js (fnm) ---
3 collapsed lines
22
export FNM_DIR="$HOME/.fnm"
23
if command -v fnm &>/dev/null; then
24
  eval "$(fnm env --use-on-cd)"
25
fi

Why fnm over nvm/Volta: fnm (Fast Node Manager) is written in Rust and initializes in ~5ms versus nvm’s 500-2000ms. The --use-on-cd flag auto-switches versions when entering directories with .nvmrc or .node-version files. fnm is now listed as the default download option on nodejs.org.

Migration note: Volta was previously recommended here but is now unmaintained as of 2024. The Volta team recommends migrating to mise or fnm. Existing Volta installations continue to work but won’t receive updates for OS changes or ecosystem breakages.

History Configuration

1
export HISTFILE="$HOME/.zsh_history"
2
export HISTSIZE=100000
3
export SAVEHIST=100000
4

5
setopt EXTENDED_HISTORY        # Write format ':start:elapsed;command'
6
setopt SHARE_HISTORY           # Share across all sessions (implies INC_APPEND_HISTORY)
7
setopt HIST_EXPIRE_DUPS_FIRST  # Expire duplicates first when trimming
8
setopt HIST_IGNORE_ALL_DUPS    # Delete old duplicate when new is added
9
setopt HIST_FIND_NO_DUPS       # Don't show duplicates in search
10
setopt HIST_IGNORE_SPACE       # Don't record commands starting with space
11
setopt HIST_SAVE_NO_DUPS       # Don't write duplicates to file
12
setopt HIST_REDUCE_BLANKS      # Strip extra whitespace
13
setopt HIST_VERIFY             # Expand history before executing

Why 100K entries: Disk is cheap; losing a command you ran six months ago is expensive. The deduplication options (HIST_IGNORE_ALL_DUPS, HIST_SAVE_NO_DUPS, HIST_FIND_NO_DUPS) prevent bloat from repeated commands.

Why SHARE_HISTORY alone: It implicitly enables INC_APPEND_HISTORY. Setting both can cause conflicts. EXTENDED_HISTORY adds timestamps, enabling time-based search and forensics.

Prefix-Based History Search

1
bindkey '^[[A' history-beginning-search-backward   # Up arrow
2
bindkey '^[[B' history-beginning-search-forward    # Down arrow

Type git co then press Up—cycles through all history entries starting with git co. This is more useful than generic reverse search for common prefixes.

Completion System

1
# Rebuild completion cache only once per day
2
autoload -Uz compinit
3
if [ "$(date +'%j')" != "$(stat -f '%Sm' -t '%j' ~/.zcompdump 2>/dev/null)" ]; then
4
  compinit
5
else
6
  compinit -C  # Skip security check, use cache
7
fi
8

9
zstyle ':completion:*' menu select
10
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}' 'r:|=*' 'l:|=*'
11
zstyle ':completion:*' completer _complete _approximate _expand_alias
12

13
setopt COMPLETE_IN_WORD
14
setopt AUTO_MENU
15
setopt AUTO_LIST

Why daily cache: compinit regenerates completion definitions on every startup unless cached. The date check rebuilds once per day; compinit -C skips security checks on subsequent loads, saving ~100-200ms.

The matcher-list enables case-insensitive matching and fuzzy completion. menu select shows a navigable menu when multiple completions exist. The completer style adds approximate matching and alias expansion.

Modern CLI Replacements

These tools are faster, have better defaults, and produce more readable output than their UNIX predecessors. All are written in Rust or Go for performance.

Note on eza: eza is the community-maintained fork of exa, which was discontinued in June 2023. eza receives active updates including new Nerd Fonts icon support.

Aliases

1
# eza aliases (requires Nerd Font)
2
alias ll="eza -lah --icons"
3
alias tree="eza --tree --level=2 --icons"
4

5
# Directory navigation
6
alias ..="cd .."
7
alias ...="cd ../.."
8

9
# Git shortcuts
10
alias gs="git status"
11
alias gl="git log --oneline --graph --decorate"
12
alias gcl='git checkout $(git branch | fzf | sed "s/^[* ]*//")'      # Local branch picker
13
alias gcr='git checkout $(git branch -r | fzf | sed "s/^[* ]*//" | sed "s/origin\///")'  # Remote branch picker

The gcl and gcr aliases pipe branch lists through fzf for interactive selection—eliminates typing branch names.

Fuzzy Finder Integration

1
if command -v fzf &>/dev/null; then
2
  source <(fzf --zsh)
3
fi

This enables (as of fzf v0.48.0+):

• Ctrl+R: Fuzzy search command history
• Ctrl+T: Fuzzy search files in current directory
• Alt+C: Fuzzy search and cd into directories

The fzf --zsh syntax is the modern shell integration method introduced in v0.48.0. It uses fzf’s built-in file walker instead of spawning find, improving performance.

Breaking change: fzf v0.51.0+ requires zsh 5.1 or later. If using an older zsh version, pin fzf to v0.50.0.

Directory Jumping with zoxide

1
if command -v zoxide &>/dev/null; then
2
  eval "$(zoxide init zsh)"
3
fi

After visiting directories, z <pattern> jumps to the most frecent (frequent + recent) match. z proj might jump to ~/work/my-project if you visit it often.

Frecency algorithm: Each directory starts with a score of 1, incremented on each access. Scores decay based on last access time. When total score exceeds _ZO_MAXAGE (default: 10000), all scores are reduced to ~90% of max, and directories below score 1 are pruned.

Dependency: zoxide v0.9.8+ requires fzf v0.51.0+ for interactive selection. Update fzf if zi (interactive mode) fails.

Shell Plugins

Autosuggestions

1
if [ -f "$HOMEBREW_PREFIX/share/zsh-autosuggestions/zsh-autosuggestions.zsh" ]; then
2
  source "$HOMEBREW_PREFIX/share/zsh-autosuggestions/zsh-autosuggestions.zsh"
3
fi

Shows grayed-out suggestions as you type, based on history. Press Right Arrow to accept.

Syntax Highlighting

1
# Must be sourced last for best compatibility
2
if [ -f "$HOMEBREW_PREFIX/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" ]; then
3
  source "$HOMEBREW_PREFIX/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"
4
fi

Colors commands, options, and paths as you type. Invalid commands appear red before you hit Enter.

Why last: The plugin hooks into the line editor. Loading it after other plugins ensures it sees the final state of each line.

Starship Prompt

Starship is a Rust-based prompt that renders in ~10ms. Configuration lives in ~/.config/starship.toml. As of v1.24.x (December 2025), Starship includes parallelized module loading and improved context detection.

Core Configuration

1
add_newline = true
2
command_timeout = 800
3
scan_timeout = 50
4

5
format = """
6
$directory$git_branch$git_status$python$nodejs$golang$java
7
$character"""

The prompt shows: directory → git branch → git status → active language version → newline → prompt character.

Prompt Character

1
[character]
2
success_symbol = "[❯](bold green) "
3
error_symbol = "[❯](bold red) "
4
vicmd_symbol = "[❮](bold yellow) "

The character changes color based on exit code—instant visual feedback for failed commands.

Git Status Symbols

1
[git_status]
2
format = "[($all_status$ahead_behind )]($style)"
3
conflicted = "≠"
4
ahead = "⇡"
5
behind = "⇣"
6
diverged = "⇕"
7
untracked = "…"
8
stashed = "⚑"
9
modified = "✚"
10
staged = "●"
11
renamed = "»"
12
deleted = "✖"

These symbols appear only when relevant. A clean repo shows nothing; a repo with staged and modified files shows ●✚.

Language Version Indicators

1
[python]
2
symbol = " "
3
format = "[$symbol$version]($style) "
4

5
[nodejs]
6
symbol = "⬢ "
7
format = "[$symbol$version]($style) "
8

9
[golang]
10
symbol = " "
11
format = "[$symbol$version]($style) "
12

13
[java]
14
symbol = "☕ "
15
format = "[$symbol$version]($style) "

Starship detects language context via marker files (package.json, go.mod, pom.xml, etc.) and displays the active version. This requires a Nerd Font for icon rendering.

Git Configuration

The Git setup uses conditional includes to load different identities based on repository path.

Base Configuration

14 collapsed lines
1
########################################
2
# ~/.gitconfig - Global Git config
3
########################################
4
#
5
# Directory conventions:
6
#   - All work repos under:     ~/work/
7
#   - All personal repos under: ~/personal/
8
#
9
# Git will automatically load:
10
#   - ~/.gitconfig-work      if repo lives under ~/work/
11
#   - ~/.gitconfig-personal  if repo lives under ~/personal/
12
########################################
13

14
[user]
15
    name = Sujeet
16
    # Email NOT set here—forces work/personal to specify
17

18
[init]
19
    defaultBranch = main
20

21
[push]
22
    autoSetupRemote = true
23
    default = simple
24
    useForceIfIncludes = true
25

26
[pull]
27
    rebase = true
28

29
[fetch]
30
    prune = true
31

32
[rebase]
33
    autoStash = true
34

35
[rerere]
36
    enabled = true
37
    autoupdate = true
38

39
[column]
40
    ui = auto
41

42
[branch]
43
    sort = -committerdate
44

45
[commit]
46
    verbose = true
47

48
[alias]
49
    co = checkout
50
    br = branch
51
    st = status -sb
52
    ci = commit
53
    lg = log --oneline --graph --decorate --all

Why no email in base config: Forces explicit configuration per context. Committing with the wrong email to a work repo (or vice versa) is a compliance issue in some organizations.

Why pull.rebase = true: Creates a linear history by replaying local commits on top of upstream changes. Cleaner than merge commits for feature branches. rebase.autoStash handles uncommitted changes automatically.

Why push.useForceIfIncludes = true (Git 2.30+): Makes --force-with-lease safer by ensuring the remote tip was actually fetched locally, preventing accidental overwrites when the remote was updated between your last fetch and push.

Why rerere.enabled = true: “Reuse Recorded Resolution” remembers how you resolved merge conflicts and auto-applies the same resolution next time. Essential for long-running branches with repeated rebases.

Why fetch.prune = true: Automatically removes remote-tracking references to deleted branches. Keeps git branch -r clean.

Why branch.sort = -committerdate: Shows most recently committed branches first in git branch output. More useful than alphabetical sorting.

Conditional Includes

1
[includeIf "gitdir:~/work/"]
2
    path = ~/.gitconfig-work
3

4
[includeIf "gitdir:~/personal/"]
5
    path = ~/.gitconfig-personal
6

7
# Alternative: match by remote URL (Git 2.36+)
8
# [includeIf "hasconfig:remote.*.url:git@github.com:mycompany/**"]
9
#     path = ~/.gitconfig-company

Git evaluates gitdir: against the repository’s .git directory path. Any repo under ~/work/ loads .gitconfig-work; repos under ~/personal/ load .gitconfig-personal.

Available conditions (as of Git 2.48):

The hasconfig:remote.*.url: condition is useful when repos aren’t organized by directory but by remote (e.g., all github.com/mycompany/* repos should use work email regardless of local path).

Personal Profile

1
[user]
2
    name = Sujeet
3
    email = contact@sujeet.pro

Work Profile

1
[user]
2
    name = Sujeet
3
    email = sujeet@company-name.com

SSH Configuration

SSH config maps hosts to identity files, enabling different keys for different services.

1
Host github.com
2
  HostName github.com
3
  User git
4
  IdentityFile ~/.ssh/id_ed25519_personal
5

6
Host bitbucket.org
7
  HostName bitbucket.org
8
  User git
9
  IdentityFile ~/.ssh/id_ed25519_work

Why Ed25519: Smaller keys (256-bit vs RSA’s 2048+), faster operations, and no known weaknesses. Ed25519 is now the default recommendation from GitHub and GitLab. RSA is only needed for legacy systems that don’t support modern algorithms.

Key generation:

ssh-keygen -t ed25519 -C "your_email@example.com"

This pattern extends to any service: add a Host block with the appropriate IdentityFile. For high-security environments, consider hardware security keys (YubiKey) which store the private key on the device.

Editor Setup

VS Code Configuration

1
{
2
  "editor.fontFamily": "'JetBrains Mono', Menlo, Monaco, 'Courier New', monospace",
3
  "editor.fontSize": 16,
4
  "terminal.integrated.fontFamily": "'JetBrainsMono Nerd Font'",
5
  "terminal.integrated.fontSize": 14,
6
  "files.associations": {
7
    "**/.gitconfig-work": "properties",
8
    "**/.gitconfig-personal": "properties",
9
    "**/starship.toml": "toml",
10
    "**/.aws/credentials": "ini",
11
    "**/.aws/config": "ini"
12
  }
13
}

Why separate fonts: The editor uses JetBrains Mono (ligatures, readability). The integrated terminal uses the Nerd Font variant for icon support in eza, starship, etc.

Recommended Extensions

Automated Setup with Ansible

The entire configuration is applied via a single Ansible playbook.

Prerequisites

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

# 2. Install Ansible
brew install ansible

# 3. Clone the dot-files repo
git clone https://github.com/your-username/dot-files.git ~/dot-files
cd ~/dot-files

Running the Playbook

ansible-playbook setup.yml --ask-become-pass

The playbook:

1. Homebrew role: Installs all CLI tools (formulae) and GUI applications (casks)
2. Dotfiles role: Creates directories, symlinks configs, sets SSH permissions, installs VS Code extensions

Homebrew Packages

1
homebrew_formulae:
2
  - aichat
3
  - ansible
4
  - awscli
5
  - bat
6
  - eza
7
  - fd
8
  - fnm
9
  - fzf
10
  - httpie
11
  - ripgrep
12
  - starship
13
  - tlrc
14
  - tree
15
  - zoxide
16
  - zsh-autosuggestions
17
  - zsh-syntax-highlighting
18

19
homebrew_casks:
20
  - cursor
21
  - visual-studio-code
22
  - chatgpt-atlas
23
  - claude
24
  - claude-code
25
  - zoom
26
  - maccy
27
  - rectangle
28
  - font-jetbrains-mono
29
  - font-jetbrains-mono-nerd-font

Dotfiles Symlinking

1
dotfiles_links:
2
  - src: ".zshrc"
3
    dest: ".zshrc"
4
  - src: ".gitconfig"
5
    dest: ".gitconfig"
6
  - src: ".gitconfig-personal"
7
    dest: ".gitconfig-personal"
8
  - src: ".gitconfig-work"
9
    dest: ".gitconfig-work"
10
  - src: ".config/starship.toml"
11
    dest: ".config/starship.toml"
12
  - src: ".ssh/config"
13
    dest: ".ssh/config"

Symlinks point from ~/.zshrc → ~/dot-files/.zshrc. Changes in either location reflect immediately. The repo is the source of truth; push changes to propagate across machines.

Productivity Applications

Window Management

Rectangle (rectangle cask): Keyboard-driven window tiling. Ctrl+Option+← snaps to left half; Ctrl+Option+→ snaps to right. Eliminates mouse-based window arrangement.

Clipboard Manager

Maccy (maccy cask): Clipboard history with fuzzy search. Cmd+Shift+C opens history; type to filter; Enter to paste. Essential when copying multiple items.

AI Tools

Conclusion

This setup optimizes for:

• Reproducibility: One Ansible command provisions a new machine
• Context isolation: Git commits, SSH keys, and directory structure enforce work/personal separation
• Keyboard efficiency: Fuzzy finders, aliases, and tiling window managers minimize mouse usage
• Modern tooling: CLI replacements that are faster and produce better output

The configuration is opinionated but modular. Swap version managers, remove unused language indicators, or add new Homebrew packages by editing the respective YAML files.

Appendix

Prerequisites

• macOS 13+ with Apple Silicon (M1/M2/M3/M4); Intel requires path adjustments (/usr/local instead of /opt/homebrew)
• Homebrew installed
• zsh 5.1+ (macOS ships with zsh 5.9 as of macOS 14)
• Basic familiarity with shell configuration and Git

Terminology

• Frecency: Frequency + recency ranking algorithm used by zoxide; balances how often and how recently a directory was visited
• Nerd Font: Font patched with 3000+ icons for terminal display (file types, git status, language logos)
• Shim: Wrapper script that intercepts commands and routes to the correct version; used by version managers like fnm and pyenv
• rerere: “Reuse Recorded Resolution”—Git feature that remembers conflict resolutions for automatic reapplication
• compinit: Zsh completion initialization; generates and caches completion definitions

Summary

• Ansible playbook automates full environment setup from a fresh macOS install
• .zshrc loads version managers, configures history, enables fuzzy search and autosuggestions; targets sub-100ms startup
• Static Homebrew paths and daily compinit caching eliminate common startup bottlenecks
• Starship prompt shows git status and language versions with ~10ms render time
• Git conditional includes (gitdir:, hasconfig:remote.*.url:) load different identities based on repo location or remote URL
• SSH config maps hosts to Ed25519 identity files for work/personal key separation
• Modern CLI tools (eza, bat, ripgrep, fzf, zoxide, fd) replace legacy UNIX utilities
• fnm replaces Volta for Node.js version management (Volta is now unmaintained)

References

• Git Configuration Documentation - Official Git config reference including conditional includes
• Zsh Options - Complete list of setopt flags
• Zsh Completion System - compinit and zstyle reference
• Starship Configuration - Prompt customization reference
• fzf Shell Integration - Modern shell setup (v0.48.0+)
• zoxide Algorithm - Frecency ranking explanation
• fnm Documentation - Fast Node Manager setup and usage
• eza Documentation - Modern ls replacement (exa fork)
• Ansible Homebrew Module - Package installation
• Volta Deprecation Notice - Migration guidance to mise/fnm