mcferrill's dotfiles

This is a set of config files mostly starting with "." (hence the repo name) that allow consistent behavior between multiple tools across environments.

Installing and Updating

Clone the repo (eg. to $HOME/.files or $HOME/dotfiles) and install with:

./install

With no command, ./install performs an idempotent, non-destructive installation.

Use ./install update to update dotfiles, submodules, packages, and plugins.

Use ./install link, ./install unlink, ./install packages, or ./install doctor for individual operations. Use ./install help for command help. Add --dry-run to inspect changes without applying them.

Managed home files live under home/ and mirror paths below $HOME. Platform-specific files live under home-darwin/, home-ubuntu/, or home-arch/. The linker walks these trees recursively and refuses to replace unmanaged files.

Packages are declared in packages.conf using one entry per line: scope type package. Use all for shared packages and darwin, ubuntu, or arch for platform-specific entries. Use auto for a shared package whose native package type is obvious. Run ./install packages list to inspect the selected package set.

Secrets

Some things like SSH keys or private configs shouldn't be used. You can use a secrets manager like bitwarden to store and sync these items.

Tools Configured

• zsh - completion, history search, syntax highlighting, and autosuggestions
• starship - terminal styling
• Git - source code management
• Tmux - terminal multiplexer (splits/tabs, etc)
• tmate - remote terminal sharing with shared tmux configuration
• herdr - a tmux-like multiplexer made for agents
• Neovim - Telescope, LSP, completion, formatting, and Treesitter (based on kickstart.nvim)
• mise - manages tool versions including Python, Node, Neovim, Starship, uv, PDM, and OpenCode
• OpenCode - TUI, package, and custom plugin configuration
• uv and PDM - Python environments and tooling
• lazygit, jq, ripgrep, fzf, git-lfs, and the Silver Searcher - command-line development tools
• wezterm - cross platform terminal emulator
• macos
  • karabiner - keyboard customization (more easily generated with this)
  • aerospace - window manager (like i3)

Per-machine config

On unixy systems you can put system specific configuration in ~/.files/sys.sh and they will also be sourced.

Currently used on

• macOS
• Ubuntu
• Arch Linux

The bin/ directory also includes tmux and Herdr sessionizers plus small cleanup and dependency utilities.