Dotfiles

Personal dotfiles for a terminal-centric workflow. Cross-platform setup for macOS and Arch Linux, with first-class support for Omarchy (DHH's Arch Linux).

Quick Start

git clone https://github.com/<your-user>/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh

The installer auto-detects your platform and picks the right strategy:

Platform	Default Mode	What Happens
macOS	full	Installs everything via Homebrew
Arch Linux	full	Installs everything via pacman
Omarchy	overlay	Keeps Omarchy base, selectively replaces configs

Installation Modes

./install.sh full        # Install everything
./install.sh overlay     # Overlay on existing setup (Omarchy)
./install.sh minimal     # Only install missing tools
./install.sh uninstall   # Remove dotfiles symlinks
./install.sh --dry-run   # Preview without changes
./install.sh --yes full  # Non-interactive

Architecture

dotfiles/
├── install.sh           # Main entry point
├── Makefile             # Quick commands (make help)
├── lib/                 # Modular shell library
│   ├── logging.sh       # Colored output utilities
│   ├── platform.sh      # OS & environment detection
│   ├── packages.sh      # Cross-platform package installer
│   ├── stow.sh          # GNU Stow wrapper with backup/restore
│   └── omarchy.sh       # Omarchy coexistence logic
├── configs/             # Stow packages (symlinked to ~)
│   ├── bash/            # .bashrc (slim wrapper)
│   ├── ghostty/         # Ghostty terminal config
│   ├── git/             # .gitconfig
│   ├── mise/            # mise global tool versions
│   ├── neovim/          # Neovim (kickstart.nvim based)
│   ├── shell/           # Shared shell modules (aliases, fzf, tools…)
│   ├── starship/        # Starship prompt config
│   ├── tmux/            # tmux config with plugins
│   ├── tools/           # Custom scripts (fzf-git, aws_creds)
│   └── zsh/             # .zshrc (slim wrapper) + vendored plugins
├── docs/                # Platform-specific guides
│   ├── archlinux.md
│   ├── macos.md
│   ├── omarchy.md       # Omarchy coexistence guide
│   └── windows_setup.md
└── .github/
    ├── workflows/lint.yml
    └── ISSUE_TEMPLATE/

How It Works

1. Detection — Identifies OS, package manager, and Omarchy presence
2. Prerequisites — Installs gum (TUI) and stow (symlinks)
3. Tools — Installs CLI tools via the platform package manager
4. Configs — Symlinks config files to ~ using GNU Stow
5. Backup — Existing configs are backed up to ~/.dotfiles-backup/ before replacement

Shell Architecture

Both .bashrc and .zshrc are slim wrappers that source shared modules from ~/.config/shell/:

~/.config/shell/
  environment.sh   # EDITOR, HISTSIZE, LANG, XDG dirs, PATH
  aliases.sh       # General, directory, safety-net, and git aliases
  fzf.sh           # fzf config, colors, previews, fzf-git
  tools.sh         # zoxide, starship, mise activation
  functions.sh     # mkcd, extract, serve, gclone, fkill, path
  ai.sh            # AI tools: Claude Code, GitHub Copilot CLI, aicommit
  tmux.sh          # tmux auto-attach, GPG agent

Each RC file only contains shell-specific setup (bash shopt options, zsh plugins) and a loop that sources the shared modules. Adding a new alias or function means editing one file instead of two.

Tools

Tool	Description
neovim	Hyperextensible text editor
tmux	Terminal multiplexer with session persistence
ghostty	Fast, native terminal emulator
fzf	Fuzzy finder for files, history, and more
fd	Fast alternative to find
bat	cat with syntax highlighting
eza	Modern ls replacement
zoxide	Smarter cd that learns your habits
ripgrep	Blazing fast recursive grep
starship	Minimal, fast, customizable prompt
mise	Dev tool version manager (node, python, go, etc.)
lazygit	Simple terminal UI for Git
sesh	Smart tmux session manager
fzf-git	Git + fzf keybindings
Claude Code	AI coding agent in the terminal
GitHub Copilot CLI	AI command suggestions (??, explain)

Keymaps

fzf

Key	Action
Ctrl-T	Fuzzy file search
Alt-C	Fuzzy directory search
Ctrl-R	History search

fzf-git

Key	Action
Ctrl-G Ctrl-F	Files
Ctrl-G Ctrl-B	Branches
Ctrl-G Ctrl-T	Tags
Ctrl-G Ctrl-R	Remotes
Ctrl-G Ctrl-H	Commit Hashes
Ctrl-G Ctrl-S	Stashes
Ctrl-G Ctrl-L	Reflogs
Ctrl-G Ctrl-W	Worktrees
Ctrl-G Ctrl-E	Each ref

tmux

Key	Action
Ctrl-A	Prefix (replaces Ctrl-B)
Prefix T	Session switcher (sesh + fzf)
Ctrl-H/J/K/L	Navigate panes (vim-aware)
Prefix H/J/K/L	Resize panes
Prefix |	Split horizontal
Prefix -	Split vertical

Neovim AI (Space + a)

Key	Mode	Action
Space a a	n	Toggle CopilotChat
Space a q	n	Quick AI question
Space a m	n	Generate commit message
Space a p	n	Prompt actions (Telescope)
Space a e	v	Explain selection
Space a r	v	Review selection
Space a f	v	Fix selection
Space a o	v	Optimize selection
Space a d	v	Generate docs
Space a t	v	Generate tests
Space a c	n	Avante: ask AI about code
Tab	i	Accept Copilot suggestion

Shell AI

Command	Action
??	AI shell command suggestion (gh copilot)
git?	AI git command suggestion
explain	Explain a command with AI
ask "..."	Quick question to Claude / Copilot
how "..."	Get a shell command for a task
aicommit	AI-generated git commit message
review file	AI code review of a file

Aliases

General

Alias	Command
vim	nvim
c	clear
ls	eza with icons
tree	Tree view (3 levels)
lg	lazygit

Git (shell aliases)

Alias	Command	Category
gs	git status -s	basics
gd / gds	git diff / --staged	basics
ga / gap	git add . / add -p (interactive)	staging
grs	git restore --staged (unstage)	staging
gc / gce	git commit -m / open editor	commits
gca / gcae	amend (silent / open editor)	commits
gcam	git commit -am (tracked + commit)	commits
gwip	quick WIP commit (skip CI)	commits
gundo	undo last commit, keep staged	commits
gsw / gswc	git switch / -c (create)	branches
gb / gba	branch / branch -a	branches
gbd / gbD	delete merged / force delete	branches
gf / gfa	fetch / --all --prune	remote
gpl / gplr	pull / --rebase	remote
gps / gpsf	push / --force-with-lease	remote
gpsu	push new branch + set upstream	remote
grbi	git rebase -i (interactive)	rebase
grbc / grba	rebase continue / abort	rebase
gst / gstp / gstl	stash / pop / list	stash
glog / gll / glp	graph / last 20 / pretty dated	log
gbl	git blame -C	utils
gcp	git cherry-pick	utils
gbclean	delete branches merged into main	utils

Git (gitconfig aliases)

Alias	Command
git undo	Reset last commit (soft)
git unstage	Restore --staged
git wip	Quick WIP commit
git unwip	Pop WIP commit
git today	Commits since midnight
git bclean	Delete merged branches
git gone	List branches with deleted remotes
git prune-gone	Delete branches with deleted remotes
git last	Diff from last commit
git aliases	List all git aliases
git root	Show repo root path

Make Commands

make help            # Show all commands
make install         # Auto-detect and install
make install-full    # Full install
make install-overlay # Overlay mode
make install-dry     # Dry-run preview
make stow-neovim     # Stow single config
make unstow-neovim   # Unstow single config
make doctor          # Check system health
make lint            # Run shellcheck
make backup          # List config backups
make restore         # Restore a backup
make update          # Pull + re-install
make version         # Show current version
make changelog       # Changes since last release

Releases

This project uses CalVer — tags follow the format YYYY.MM.DD.

Every push to main automatically creates a GitHub Release with a changelog grouped by Conventional Commits:

Prefix	Changelog Section
feat:	✨ Features
fix:	🐛 Bug Fixes
docs:	📚 Documentation
refactor:	♻️ Refactoring
chore:	🔧 Chores
perf:	⚡ Performance
ci:	👷 CI

To skip a release, add [skip release] to your commit message.

See all releases: GitHub Releases

Platform Guides

• macOS — Homebrew, iTerm2, fonts
• Arch Linux — pacman, AUR, clipboard
• Omarchy — Coexistence with DHH's Arch setup
• Windows (WSL) — Windows Terminal + WSL2

License

MIT