dotfiles

My dotfiles, managed with GNU Stow.

A .stowrc at the repo root sets --target=~ by default. Most stow commands then work without an explicit --target flag.

Setup

Prerequisites

Install Stow:

# macOS
brew install stow

# Debian/Ubuntu
sudo apt install stow

OS related setup scripts are in the setup/ folder.

Homebrew packages

The package list lives in a Brewfile owned by the brew-manage submodule (brew-manage/Brewfile). setup/setup_mac.sh installs it via brew bundle.

git submodule update --init brew-manage        # ensure submodule is present
brew bundle --file=brew-manage/Brewfile        # install taps, formulae, casks
brew bundle check --file=brew-manage/Brewfile --verbose  # what is missing
brew bundle cleanup --file=brew-manage/Brewfile          # remove strays (review!)

The submodule also puts two analysis tools on PATH: brew-info (JSON package report) and brew-deps-graph (dependency tree). Non-brew installs (bun, npm -g, gh extensions) stay in setup/setup_mac.sh.

Install

cd ~ && git clone --recursive git@github.com:theskumar/dotfiles.git
cd ~/dotfiles
./install.sh

install.sh stows all packages to $HOME and $HOME/.config based on your OS.

Installing a single package

cd ~/dotfiles
stow shell                              # packages targeting $HOME (uses .stowrc default)
stow --target="$HOME/.config" ghostty  # packages targeting $HOME/.config

Uninstalling a package

stow -D shell

Packages

Core (all machines)

Package	Contents
shell	.aliases, .bashrc, .exports, .functions, .inputrc, .profile
zsh	.zshrc, .zshenv, .zsh/ (plugins, functions, lib)
git	.gitconfig, .gitmessage, .gitattributes, .config/git/ignore
vim	.vimrc, .vim/
tools	.ackrc, .actrc, .carbon-now.json, .cookiecutterrc, .curlrc, .nuxtrc, .pythonrc.py, .wgetrc
ssh	.ssh/config.sample
fonts	.fonts/ (Hermit, Source Code Pro)
claude	.claude/settings.json, .claude/bin/statusline-git.cjs (statusline wrapper)

Editor and terminal (XDG, stowed to ~/.config)

Package	Contents
ghostty	Terminal config with tmux keybind layer
zed	settings.json, keymap.json, tasks.json, snippets/
lazygit	Zed as external editor
starship	Prompt config
tmux	tmux.conf, tmux.reset.conf
sesh	Tmux session definitions
tmuxinator	Project layouts
mise	Global tool versions config
helix	config.toml (editor settings, theme, keybinds), languages.toml (LSPs, formatters)
herdr	config.toml (keybindings, theme, plugins)

Git and dev tools (XDG)

Package	Contents
gh	GitHub CLI config (aliases)
gh-dash	GitHub dashboard layout
jj	Jujutsu VCS config (user, editor, git backend) + jjui TUI config
worktrunk	Git worktree path templates

macOS specific

Package	Target	Contents
macos	$HOME	.finicky.js, .osx
omniwm	~/.config	OmniWM tiling WM (niri/dwindle layouts), workspaces, hotkeys, app rules
karabiner	~/.config	Keyboard customization (karabiner.json — app launchers, vim arrows, caps→ctrl/esc)

Linux specific

Package	Contents
linux	.linux, .xmobarrc, .Xresources, .xsession, .xsessionrc

Other

Package	Contents
freebsd	.freebsd

Not stowed

Directory	Why
bin/	Scripts added to PATH via .exports, not symlinked
brew-manage/	Git submodule: Brewfile + brew analysis tools (brew-info, brew-deps-graph on PATH)
setup/	One-shot install scripts, run manually
pi/	AI coding agent settings (~/.pi/agent/settings.json), stow manually if needed
.private/	Gitignored secrets

Docs

Guides and references in docs/:

File	Topic
TMUX.md	Tmux keybindings and workflow
OMNIWM.md	OmniWM tiling window manager
NEWSBOAT.md	Newsboat RSS reader
MOSH.md	Mosh mobile shell setup and usage
PI-TREE.md	Pi agent tree, branch, and fork workflows
HERDR.md	Herdr keybindings, plugins, and workflow

Notes

install.sh copies ~/.gitignore; it does not symlink it. Stow skips .gitignore files by default.