Skip to content

Making Your Shell Environment Portable: Dotfiles, Git, and 10x Zsh Everywhere

A guide to ensuring your terminal is always powerful, familiar, and productive—on any machine, local or remote.

Why Portability Matters

  • A great shell setup is a superpower—but only if you have it everywhere you work: local, remote, new laptops, cloud VMs, etc.
  • The terminal only "sucks" when it's not set up right. With a portable, versioned config, you're always at home in your shell.

What Are Dotfiles?

  • "Dotfiles" are your shell and tool config files (e.g., .zshrc, .gitconfig, .vimrc, etc.).
  • Managing them with Git lets you:
  • Instantly set up a new machine or remote server.
  • Keep your config in sync everywhere.
  • Experiment safely (rollback, branch, etc.).
  • Share and learn from others' setups.

Strategies for Managing Dotfiles

  • Store your dotfiles in a Git repo (e.g., ~/dotfiles).
  • Symlink them into your home directory.
  • Example:

sh ln -s ~/dotfiles/.zshrc ~/.zshrc

2. Bare Git Repo ("Dotbare" Pattern)

  • Keep your home directory as the working tree, but store the Git repo elsewhere.
  • No symlinks needed; files live in ~.
  • Example setup:

sh git clone --bare git@github.com:yourname/dotfiles.git $HOME/.dotfiles alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME' dotfiles checkout

3. Dotfile Managers

  • Tools like chezmoi, yadm, or rcm automate syncing, templating, and OS-specific config.

Keeping Secrets Out of Dotfiles

  • Never commit secrets (API keys, tokens, etc.) to your dotfiles repo.
  • Use .gitignore for local-only files (e.g., .zshrc.local).
  • Consider tools like git-crypt or sops for encrypted secrets if needed.

Bootstrapping Your Environment Anywhere

  1. Clone Your Dotfiles Repo

sh git clone <repo-url> ~/dotfiles-examples cd ~/dotfiles-examples ./bootstrap.sh

  1. Customize as Needed
  2. Add plugins, aliases, or modular configs to zshrc.d/.
  3. Place secrets in .zshrc.local (never commit this file).

Making .zshrc Portable: OS & SSH Detection

See dotfiles-examples/.zshrc for a full example.

OS Detection Example:

if [[ "$OSTYPE" == "darwin"* ]]; then
  export OS_TYPE="macos"
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
  export OS_TYPE="linux"
fi

SSH Session Detection Example:

if [[ -n "$SSH_CONNECTION" ]]; then
  export IS_SSH="1"
  # Optionally disable heavy plugins, change prompt, etc.
fi

Conditional Plugin Loading Example:

if [[ "$OS_TYPE" == "macos" ]]; then
  # macOS-specific plugins or paths
elif [[ "$OS_TYPE" == "linux" ]]; then
  # Linux-specific plugins or paths
fi

Syncing to Remote Servers

  • SSH into your remote box.
  • Clone your dotfiles repo and run your bootstrap/install script.
  • Use SSH detection in .zshrc to adjust your environment (e.g., lighter prompt, fewer plugins).

Example: Reference Dotfiles

  • See the dotfiles-examples/ directory in this repo for a real-world, cross-platform, SSH-aware setup.
  • Features:
  • OS and SSH detection in .zshrc
  • Modular config (split into zshrc.d/)
  • Bootstrap script for new machines
  • .gitignore for secrets/local overrides

Agent Prompts

  • "Help me set up a dotfiles repo for my shell config."
  • "How do I sync my Zsh setup to a remote server?"
  • "Show me how to detect SSH or OS in my .zshrc."
  • "What's the best way to keep secrets out of my dotfiles?"

Resources

Tip: A portable shell is a force multiplier. Invest in your dotfiles and you'll always feel at home in the terminal—anywhere.