Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

127 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

dotfiles

Personal dotfiles managed with chezmoi.

Quick start

Fresh machine (one-liner):

sh -c "$(curl -fsLS get.chezmoi.io)" -- \
  init --apply bkahlert --source ~/.local/share/chezmoi

Existing machine:

brew install chezmoi
chezmoi init --apply bkahlert

How it works

  • chezmoi manages dotfiles — copies files to $HOME (no symlinks). Source state lives in home/ (via .chezmoiroot).
  • ZDOTDIR — zsh config lives in ~/.config/zsh/, only ~/.zshenv remains in $HOME.
  • Sheldon — zsh plugin manager (TOML config, Rust-based).
  • Starship — cross-shell prompt (TOML config, Rust-based).
  • Autoloaded functions — zsh-specific functions are files in functions/, loaded on first call.
  • Standalone scripts — shell-agnostic utilities under home/dot_local/exact_bin/ mirror ~/.local/bin exactly: removing a script from the repo removes it from the target.
  • AI assistant configs~/.claude/, ~/.gemini/, and ~/.config/agents/ are tracked so prompt rules and slash commands stay in sync across machines.

Making changes

Dotfiles (chezmoi)

chezmoi edit ~/.gitconfig         # edit a managed file
chezmoi diff                      # preview pending changes
chezmoi apply                     # apply changes to $HOME
chezmoi add ~/.config/foo/config  # start managing a new file

See chezmoi daily operations.

Zsh modules

Add a new module — create a numbered .zsh file in conf.d/:

chezmoi edit ~/.config/zsh/conf.d/10-mytool.zsh

Add a new function — create a file in functions/ named after the function. The file contains only the function body (no funcname() { wrapper):

chezmoi edit ~/.config/zsh/functions/myfunction
# Example: functions/greet
echo "Hello, ${1:-world}!"

Plugins (Sheldon)

Edit the plugin list:

chezmoi edit ~/.config/sheldon/plugins.toml

Add a plugin by adding a [plugins.<name>] section:

[plugins.my-plugin]
github = "author/repo"

Update all plugins:

sheldon lock --update

See Sheldon documentation.

Prompt (Starship)

Edit the prompt configuration:

chezmoi edit ~/.config/starship.toml

Changes take effect on the next prompt render (no restart needed).

See Starship configuration.

Ghostty

Edit the terminal configuration:

chezmoi edit ~/.config/ghostty/config

Live reload: press Cmd+Shift+, (macOS) or Ctrl+Shift+, (Linux).

See Ghostty configuration reference.

Zsh load order

~/.zshenv                       → sets ZDOTDIR
~/.config/zsh/.zprofile         → Homebrew shellenv
~/.config/zsh/.zshrc            → autoloads functions, sources conf.d/*
  00-context.zsh.tmpl           → stamps $DOTFILES_CONTEXT
  01–07                         → core (options, history, completions,
                                  keybindings, prompt, aliases, plugins)
  08-print.zsh                  → printf helpers
  10-*.zsh                      → tool modules
  20-claude.zsh                 → Claude CLI
  conf.d/$DOTFILES_CONTEXT/     → context-specific overrides (sourced last)

Testing in a container

Build and test with Podman:

make build      # build Fedora + Ghostty + VNC image
make validate   # apply dotfiles + verify zsh starts
make run        # start container with VNC on :5901
make vnc        # open VNC viewer
make stop       # stop the container
make clean      # remove the image

Repairing the startup LaunchAgent

The ~/.startup script runs at login via a LaunchAgent. If it stops working:

# Re-run the chezmoi setup script
chezmoi apply --force

Or manually recreate:

launchctl unload ~/Library/LaunchAgents/com.user.startup.plist 2>/dev/null
chezmoi state delete-bucket --bucket=scriptState
chezmoi apply

About

Personal dotfiles — chezmoi-managed zsh setup with Sheldon, Starship, Ghostty, lazy-loaded plugins, and 1Password secrets. macOS + Linux.

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages