_dotfiles

Personal configuration files — symlinked, versioned, and ready to clone.

---

Table of Contents

• What's in here
• Fresh machine setup
• Stow reference
• Day-to-day workflows
• Recovering from conflicts
• Security
• Quick cheatsheet

---

What's in here

All configs live under .config/ and are symlinked into ~/.config via GNU Stow. The repo root mirrors your home directory — stow creates the links, git tracks the content.

Color Scheme

My setup consists of auto theme switching with catppuccin. Latte for light, and Macchiato for dark. For tmux this is done by setting up hooks and with LazyVim this is done with the plugin auto-dark-mode

Shell

Config	What it does
zsh	Primary shell — functions, completions, abbreviations, and $PATH setup all live here
fish	Friendly interactive shell config with conf.d hooks for atuin and toolchain env setup
nushell	Nu shell config for when you want structured data pipelines instead of text streams
starship	Cross-shell prompt that shows only what's relevant: git state, language versions, exit codes
atuin	Replaces shell history with a searchable, syncable SQLite database

Editor & Terminal

Config	What it does
nvim	LazyVim — a full IDE setup without the config sprawl
zed	Fast native editor for when you want to stay out of the terminal
ghostty	GPU-accelerated terminal with a sane default config and zero latency
tmux	Session persistence and window management; auto theme switching between Catppuccin Latte/Macchiato on macOS appearance change, with battery status in the status bar
sesh	Smart tmux session manager with zoxide integration; dotfiles session pre-configured to open nvim on attach
zellij	Multiplexer alternative with named layouts: desktop, laptop, devops, dual-agent, my-default

TUI Tools

Config	What it does
lazygit	Git operations without memorizing flags — branches, rebases, and diffs in a single view
lazydocker	Container and image management TUI that replaces most docker invocations
k9s	Kubernetes cluster management from the terminal; essential when kubectl get isn't enough
yazi	Terminal file manager with previews, bulk operations, and plugin support
television	Fuzzy finder built for speed — a ripgrep-powered fzf alternative
hunk	Patch review and staging TUI

System & Productivity

Config	What it does
karabiner	Keyboard remapping at the driver level — complex modifications, home-row mods, layer switching
mise	Runtime version manager for Node, Python, Ruby, and anything else — replaces nvm, rbenv, pyenv
bat	cat with syntax highlighting, line numbers, and git diff markers
btop	System monitor with a layout that actually uses your terminal width
gh	Official GitHub CLI — PRs, issues, workflows, and releases from the terminal
gh-dash	Dashboard TUI for gh — all your open PRs and issues in one view
raycast	Launcher extensions and scripts
sqruff	SQL linter and formatter config
bucky	Local configuration for this setup's custom tooling

---

Fresh machine setup

Prerequisites: brew install stow

git clone <repo-url> ~/Developer/personal/dotfiles

Before stowing, back up any existing configs that would conflict. Stow refuses to overwrite real files — it errors rather than silently clobbering:

cd ~/.config
for dir in atuin bat btop bucky fish gh gh-dash ghostty hunk k9s karabiner \
           lazydocker lazygit mise nushell nvim raycast sesh sqruff starship \
           television tmux yazi zed zellij; do
  [ -d "$dir" ] && mv "$dir" "${dir}.bak"
done

Then create the symlinks:

cd ~/Developer/personal/dootfiles
stow --target="$HOME" .

That's it. Every tool that reads from ~/.config will now pick up the versioned config.

Verify it worked: readlink ~/.config/tmux should print ../Developer/personal/dotfiles/.config/tmux

---

Stow reference

Dry run — preview without touching anything

Always run this first on an unfamiliar machine:

stow -nv --target="$HOME" .

Prints every link that would be created or removed. Nothing is changed.

Stow — create symlinks

stow --target="$HOME" .

Idempotent. Already-correct symlinks are left alone — safe to re-run anytime.

Restow — sync after changes

stow --restow --target="$HOME" .

Unstow + stow in a single step. Run this after adding a new tool config, renaming a directory, or pulling in someone else's changes.

Unstow — remove all symlinks

stow --delete --target="$HOME" .

Removes every symlink stow created. Your .bak directories are untouched — rename them back to restore the originals.

Verbose output

stow --verbose --target="$HOME" .
# combine with dry run:
stow -nv --target="$HOME" .

---

Day-to-day workflows

Adding a new app's config

Move the existing config into the repo, then restow:

mv ~/.config/newapp ~/Developer/personal/dootfiles/.config/newapp
cd ~/Developer/personal/dootfiles
stow --restow --target="$HOME" .

Then commit the new directory. The symlink is live immediately — no restart needed.

Removing an app from stow

# Remove from repo
rm -rf ~/Developer/personal/dootfiles/.config/oldapp

# Clean up the now-dead symlink
stow --restow --target="$HOME" .

The app will recreate ~/.config/oldapp fresh on next launch using its own defaults.

---

Recovering from conflicts

If stow exits with a conflicts error, a real file (not a symlink) exists at the target path. Two options:

# Option 1: back it up and re-run
mv ~/.config/problem-app ~/.config/problem-app.bak
stow --target="$HOME" .

# Option 2: adopt it — stow moves the file INTO the repo and links back
# Use this only if you want to pull the existing file into your dotfiles
stow --adopt --target="$HOME" .
git diff  # always review before committing — adopt can be destructive

Note on --adopt: This flag rewrites the file in your repo to match what's on disk. If the on-disk version is worse than what you had committed, you'll overwrite your config. Check git diff before you git add anything.

---

Security

Never commit credentials to this repo.

API keys, tokens, session cookies, and passwords do not belong here. The right pattern:

• Machine-specific secrets live in a file sourced outside this repo (e.g. ~/.config/fish/local.fish added to .gitignore)
• Long-term secrets belong in a password manager or secrets manager, not in any dotfile
• If you accidentally commit a secret, treat it as compromised immediately — git history is public

---

Quick cheatsheet

# Preview what stow will do (always run first)
stow -nv --target="$HOME" .

# Create / update symlinks
stow --target="$HOME" .

# Sync after adding or moving configs
stow --restow --target="$HOME" .

# Remove all symlinks
stow --delete --target="$HOME" .

# Verify a specific symlink
readlink ~/.config/fish