Portable dotfiles

This repository uses GNU Stow to deploy the common package and, when available, a platform package (macos, linux, or wsl). It deliberately deploys a broad configuration tree, while package-local .stow-local-ignore files exclude credentials, generated files, and mutable runtime state.

Install

Clone with the pinned Neovim and TPM submodules, then run bootstrap. The bootstrap script detects the host by default; --platform macos|linux|wsl overrides detection.

git clone --recurse-submodules git@github.com:johnseth97/.dotfiles.git ~/.dotfiles
~/.dotfiles/common/.bin/bootstrap

On macOS, bootstrap uses Homebrew (installing it after Command Line Tools if needed) and applies macos/Brewfile. On Linux and WSL it uses Homebrew when present, otherwise apt, dnf, or pacman to install the core shell/deployment dependencies. Use --dry-run to show the Stow deployment, --skip-packages when dependencies are already installed, or --skip-tmux-plugins to defer TPM's initial plugin installation.

Run bootstrap-git-signing separately after installing 1Password if you want Git SSH signing configured through its agent.

Deployment policy

Stow and Git solve different problems:

• .gitignore controls what is committed.
• .stow-local-ignore controls what is deployed to $HOME.
• Application-owned caches, secrets, and plugin checkouts stay local even if an application writes them below a configuration directory.

Do not invoke stow .. Use the wrapper so platform selection and ignore policy stay consistent:

~/.dotfiles/common/.bin/dotfiles-stow --dry-run
~/.dotfiles/common/.bin/dotfiles-stow --restow

Neovim is an independently versioned project and remains a pinned submodule. Bootstrap and sync check out the revision pinned by this repository; they do not pull its branch. TPM is likewise a pinned submodule, while its installed plugins are mutable local state managed by TPM.

Update

sync-dotfiles updates only the dotfiles repository and its pinned submodules, then restows the selected packages. It refuses a dirty worktree or dirty submodule rather than overwriting local work.

sync-dotfiles

Package updates remain the responsibility of the platform package manager (Homebrew and brew-watchtower on macOS). Antidote is loaded from a packaged installation when one is available; a legacy ~/.antidote clone is only a fallback for hosts without one.