dotfiles

This repository manages shell, Git, and Vim configuration for macOS and Linux. The setup script prepares the canonical checkout for the current OS and creates links in the home directory.

The configuration is environment-specific. The macOS files expect Homebrew, Java 25, Docker Desktop completion, and the 1Password SSH agent; the Linux files do not configure Git signing or GitHub CLI authentication.

Requirements

• macOS (Darwin) or Linux
• POSIX sh for the setup script; Bash can run it as well
• Zsh for the installed shell configuration
• Git for checkout and setup
• Homebrew at /opt/homebrew/bin for the macOS configuration

The macOS configuration also refers to /usr/libexec/java_home, Docker completion files, and the 1Password SSH-agent socket. Install or adapt those dependencies before using the macOS links on another machine.

Both OS configurations assume Zsh as the login and interactive shell. The setup script itself uses POSIX sh and continues when Zsh is unavailable, but it prints a warning because the installed shell configuration cannot be used until Zsh is installed.

Quick start

Clone the repository to the canonical path, then run the setup script.

macOS

mkdir -p "$HOME/src/github.com/ssobue"
git clone https://github.com/ssobue/dotfiles.git "$HOME/src/github.com/ssobue/dotfiles"
"$HOME/src/github.com/ssobue/dotfiles/setup-dotfiles.sh"

Linux

mkdir -p "$HOME/src"
git clone https://github.com/ssobue/dotfiles.git "$HOME/src/dotfiles"
"$HOME/src/dotfiles/setup-dotfiles.sh"

The script uses $HOME/src/github.com/ssobue/dotfiles on macOS and $HOME/src/dotfiles on Linux. If the canonical checkout does not exist, the script clones it before installing links.

The script prints progress messages with the [setup-dotfiles] prefix. Errors are printed to standard error with the ERROR marker.

Installed files

File	macOS target	Linux target	Purpose
setup-dotfiles.sh	Run directly	Run directly	Prepare the checkout and install links
zshenv.mac	~/.zshenv	-	macOS environment variables and PATH
zshenv.linux	-	~/.zshenv	Linux environment variables
zshrc.mac	~/.zshrc	-	macOS interactive-shell settings
zshrc.linux	-	~/.zshrc	Linux interactive-shell settings
gitconfig.mac	~/.gitconfig	-	macOS Git settings
gitconfig.linux	-	~/.gitconfig	Linux Git settings
gitignore_global.mac	~/.gitignore_global	-	macOS global Git ignore rules
vimrc	~/.vimrc	~/.vimrc	Shared Vim settings

Edit the files in this repository, not the linked files in the home directory.

Existing files and reruns

The setup script is idempotent:

• A correct link is kept unchanged.
• An incorrect link is replaced.
• A regular file is moved to <target>.bak before the link is created.
• An existing <target>.bak is never overwritten, so setup stops with an error.
• Directories are not backed up and may cause link creation to fail.

Home-directory links refer to the repository files, so updating the checkout normally does not require another setup run. Rerun the script after switching operating systems or changing a link manually.

OS-specific behavior

macOS

• zshenv.mac prepends $HOME/.local/bin, JetBrains Toolbox, and /opt/homebrew/bin in that order.
• dotfiles_setup_path removes duplicate PATH entries.
• zshrc.mac reapplies the PATH function after macOS path_helper runs from /etc/zprofile.
• gitconfig.mac includes the Git identity, SSH signing through 1Password, the gh authentication helper, and the global ignore-file reference.

Linux

• zshrc.linux uses GNU ls options and loads ~/.zshrc_local when that file exists.
• gitconfig.linux does not configure a signing key, commit signing, or a GitHub CLI authentication helper.

The Git identity and signing configuration are machine or user specific. Replace them before distributing the configuration to another user, and keep only values that are safe to publish publicly.

Customization

• Use ~/.zshrc_local for Linux-only personal shell additions.
• Update both Git configuration files when changing shared Git behavior.
• Update gitignore_global.mac, gitconfig.mac, setup-dotfiles.sh, and this file together when changing macOS global Git ignores.
• Update the setup script, this file's installed-files table, and the relevant OS-specific files when adding or renaming a managed file.

Do not add private keys, access tokens, passwords, or other non-public information to the repository.

Verification

Run these checks after configuration changes:

bash -n setup-dotfiles.sh
sh -n setup-dotfiles.sh
zsh -n zshenv.linux zshenv.mac zshrc.linux zshrc.mac
git config --file gitconfig.mac --list >/dev/null
git config --file gitconfig.linux --list >/dev/null
git diff --check

When shellcheck is available, also run:

shellcheck setup-dotfiles.sh

Use an isolated test HOME and checkout when testing setup behavior. Do not move or replace files in the real user's home directory during verification.