Dotfiles Setup

This repo uses GNU Stow to manage dotfiles as symlinks in your home directory and uses TPM to install tmux plugins declared in tmux/.config/tmux/tmux.conf.

Packages managed by Stow

Packages are processed in this install/restow order:

1. mise
2. zsh
3. starship
4. tmux
5. nvim
6. ghostty
7. btop
8. git
9. psql
10. agents

For removal, the script runs the individual remove commands in reverse order.

Prerequisites

1. Clone this repo
2. Run commands from the repo root

Steps

1. Install Everything

For a full setup on a new machine, run:

./run.sh install

To skip the automatic shell reload at the end:

./run.sh install --no-reload-shell

This installs system bootstrap packages (jq and stow) if needed, installs mise if needed, stows the mise config, runs mise install, stows the remaining packages (zsh, starship, tmux, nvim, ghostty, btop, git, psql, and agents), then bootstraps TPM and installs tmux plugins from tmux.conf.

2. Individual Commands

Install system bootstrap packages:

./run.sh install-system

Preview dotfile changes first:

./run.sh dry-run

Install packages individually:

./run.sh install-mise
./run.sh install-zsh
./run.sh install-starship
./run.sh install-tmux
./run.sh install-nvim
./run.sh install-ghostty
./run.sh install-btop
./run.sh install-git
./run.sh install-psql
./run.sh install-agent-skills

You can also skip shell reload for install-zsh:

./run.sh install-zsh --no-reload-shell

Remove packages individually:

./run.sh remove-zsh
./run.sh remove-mise
./run.sh remove-starship
./run.sh remove-tmux
./run.sh remove-nvim
./run.sh remove-ghostty
./run.sh remove-btop
./run.sh remove-git
./run.sh remove-psql
./run.sh remove-agent-skills

Install tmux TPM and the tmux plugins declared in tmux/.config/tmux/tmux.conf:

./run.sh install-tmux-tpm

3. Install tmux TPM

Run this after installing dotfiles individually if you want to bootstrap TPM separately:

./run.sh install-tmux-tpm

What it does:

1. Ensures tmux/.config/tmux/plugins exists
2. Clones TPM into tmux/.config/tmux/plugins/tpm
3. Re-stows the tmux package
4. Loads tmux config from $HOME/.config/tmux/tmux.conf
5. Runs TPM's install_plugins command to fetch plugins listed in tmux.conf

This step requires both git and tmux to be installed.

4. Restow

Use this after changing files in the repo to refresh symlinks in the same defined order:

./run.sh restow

5. Remove

Remove all symlinks created by stow in reverse order:

./run.sh remove

Notes

• Symlinks target $HOME
• If a target file already exists, stow may report a conflict
• Back up or remove conflicting files before installing
• install-system uses brew on macOS or pacman on Linux to install jq and stow
• mise bootstrap package definitions currently include brew:jq, brew:stow, pacman:jq, and pacman:stow
• mise bootstrap currently supports zsh and bash based on $SHELL
• .zshrc defensively initializes mise, starship, and fzf only when those binaries are available
• install is the one-command bootstrap for a new machine, includes every package plus tmux TPM/plugin setup, and reloads the shell by default
• install-mise installs mise with the shell-appropriate bootstrap URL when needed, ensures system bootstrap packages are installed, stows its config, and runs mise install
• install-zsh reloads the shell by default after stowing .zshrc; pass --no-reload-shell to skip that
• install-zsh, install-starship, install-tmux, install-nvim, install-ghostty, install-btop, install-git, install-psql, and install-agent-skills each stow only their matching package
• remove-zsh, remove-mise, remove-starship, remove-tmux, remove-nvim, remove-ghostty, remove-btop, remove-git, remove-psql, and remove-agent-skills each unstow only their matching package
• restow re-stows all managed packages to refresh symlinks after repo changes
• remove runs all package remove commands in reverse install order

psql configuration

The psql package manages ~/.psqlrc and sets the pager to less -SRXF on startup:

\setenv PAGER 'less -SRXF'
\pset pager always

To apply just the PostgreSQL client config:

./run.sh install-psql

This creates a symlink at ~/.psqlrc via Stow.

Git identity configuration

The git config in this repo uses Git conditional includes to switch the commit [user] name and email based on the repository's remote URL. Your fallback identity lives directly in ~/.config/git/config-identities, with optional conditional overrides below it.

How it works

1. The main config (git/.config/git/config) includes one local file at the end:

[include]
  path = ~/.config/git/config-identities

2. ~/.config/git/config-identities is not committed (it is ignored by git/.config/git/.gitignore). It contains your default [user] identity at the top plus any includeIf rules for more specific identities:

[user]
  name = Your Name
  email = your.default.email@example.com

[includeIf "hasconfig:remote.*.url:git@github.com:my-org/**"]
  path = config-my-org

3. A matched identity file overrides the [user] section:

[user]
  name = Your Name
  email = your.work.email@example.com

Setting up your identities

1. Copy the template:

cp git/.config/git/config-identities.template git/.config/git/config-identities

2. Edit git/.config/git/config-identities and set your default identity at the top:

[user]
  name = Your Name
  email = your.default.email@example.com

3. Create a per-identity file, for example git/.config/git/config-work:

[user]
  name = Your Name
  email = your.work.email@example.com

4. Add a conditional include in git/.config/git/config-identities:

[includeIf "hasconfig:remote.*.url:git@github.com:my-org/**"]
  path = config-work

5. Re-stow the git package so the files are linked into ~/.config/git/:

./run.sh install-git

6. Test it by running git config user.email inside repositories whose remote URLs match and do not match the pattern.

Sharing the setup with teammates

If someone asks how the identity switching works, you can share this short summary:

Our dotfiles use Git's conditional includes. The main git config loads ~/.config/git/config-identities, which contains your default [user] name/email at the top plus optional includeIf rules for repo-specific identities. Matching rules load config-<name> files that override the identity for those repos. These files are gitignored, so they stay personal and are never committed. To set them up, copy config-identities.template to config-identities, set your default identity there, create any config-<name> override files you need, add the matching includeIf rules, and run ./run.sh install-git.