Dotfiles

Personal dotfiles, managed with GNU Stow.

Structure

In order to leverage the capabilities of stow, and to avoid a noisy home directory, I have split into Stow packages so a given machine only installs what it needs:

• shell: bash entry point plus shared shell scripts (snippets, env vars, aliases, ssh-agent setup). Should work everywhere, mostly POSIX compliant, certainly compliant with modern bash.
• zsh: zsh entry point, zinit plugin manager, oh-my-posh prompt. Desktop/interactive use; if you install shell alongside it, it will source the shared scripts from there.
• git: gitconfig and the allowed-signers file for verifying signed commits. Also includes lazygit config, even if it's not in every system, it's just a tiny text file.
• nvim: Neovim config.
• helix: Helix config.
• ghostty: Ghostty terminal config.
• vscodium: VSCodium user settings and extensions list.
• dotfiles-manager: the dotfiles.py CLI itself, an interactive picker (or non-interactive flags) on top of stow, plus a per-machine manifest of what's installed. Requires Python. See dotfiles-cli.md for the full reference.

Install

git clone <repo-url> ~/.dotfiles
cd ~/.dotfiles
stow -R <packages   # -R removes first stows later, clears stale links
stow -D <package>   # Delete a dotfile package

Or stow dotfiles-manager to get a dotfiles.py command on PATH that wraps the same stow calls, which provides a TUI, a CLI and can be piped from curl to python to even clone the repo for you in the first place

Man page

dotfiles-cli.md documents the CLI, after editing the docs, remember to regenerate it with the following command:

pandoc -s -t man -M title=DOTFILES -M section=1 -M date="$(date +'%B %Y')" \
  -o dotfiles-manager/dot-local/share/man/man1/dotfiles.py.1 dotfiles-cli.md

man looks pages up by the exact command name, so the page has to be named dotfiles.py.1 to match the dotfiles.py command, not dotfiles.1. Once the package is stowed, ~/.local/share/man is already on MANPATH by default on most systems, so man dotfiles.py works with no further setup.

Requirements

• stow
• git
• python3 (optional, for the CLI)

Each package configures specific programs, those programs are obviously required for the package to have any effect, zsh/ needs zsh installed and configured, it only applies a zshrc, it doesn't install the program.

An exception to this is zinit and oh-my-posh, which are automatically pulled when first executing zshrc

In addition, the shell package will configure aliases and environments for additional programs that may or may not be installed. These aren't required but will be configured if present