The Complete Guide to Syncing Your Zsh Configuration

Most developers think of their shell config as a single file: .zshrc. In reality, a complete Zsh setup spans multiple files, each loaded at different stages of shell initialization:

• ~/.zshenv — loaded for every shell (including scripts), sets environment variables
• ~/.zprofile — loaded for login shells, sets PATH and session-level variables
• ~/.zshrc — loaded for interactive shells, your aliases, plugins, prompt, and keybindings
• ~/.aliases — a common convention for separating alias definitions

If you only sync .zshrc, you will lose environment variables set in .zshenv, PATH entries from .zprofile, and any aliases broken out into a separate file. ConfigSync tracks all four by default.

A single command detects and tracks your entire Zsh configuration:

This automatically discovers .zshrc, .zprofile, .zshenv, and .aliases if they exist. All four files are captured in a single snapshot whenever you push.

On a new machine, pulling restores every file to the correct location:

If you work across macOS and Linux, your PATH and tool locations differ. Homebrew on macOS installs to /opt/homebrew/bin, while Linux package managers use /usr/local/bin. ConfigSync templates handle this cleanly:

When ConfigSync restores this file, it evaluates the template for the current platform. Your macOS machine gets Homebrew paths. Your Linux server gets the correct alternatives. One config file, zero manual editing.

Oh My Zsh stores custom plugins and themes in ~/.oh-my-zsh/custom/. The built-in plugins ship with Oh My Zsh and do not need syncing, but any custom plugins or themes you have added do.

On the new machine, install Oh My Zsh first (it takes ten seconds), then pull your ConfigSync snapshot. Your custom plugins and themes land in the right directory automatically.

If you use Starship instead of (or alongside) Oh My Zsh themes, its configuration lives in a single file: ~/.config/starship.toml. ConfigSync has a dedicated module for it:

Starship is cross-shell, so the same starship.toml works whether you are using Zsh on macOS, Bash on a Linux server, or Fish on your personal laptop. This makes it an ideal candidate for syncing: one config file produces the same prompt everywhere.

After pulling new shell configuration, your current terminal session still has the old config loaded. You can set up a post-pull hook to source the new config automatically:

This runs source ~/.zshrc after every pull that touches Zsh files. Your current session picks up the new aliases and functions immediately without opening a new terminal window.

Here is the complete setup for syncing your entire Zsh environment:

From a blank machine to your fully customized shell in under two minutes. Every alias, every function, every prompt tweak, every plugin, all restored exactly as you left them.