Kergoth's Dotfiles and Setup Scripts

Personal dotfiles and system setup, managed with chezmoi and Nix Home Manager. This repository covers application configuration, shell customization, package installation, and system-level setup across macOS, Linux, FreeBSD, and Windows. All machine-specific differences and optional feature flags are handled through chezmoi's template system.

How It Works

Chezmoi manages dotfiles: it templates configuration files, applies them to $HOME, handles encrypted secrets via age, and runs setup scripts as part of the apply process. Nix Home Manager provides the primary method of declarative, reproducible package management at the user level where Nix and nixpkgs are viable, supplemented by Homebrew on macOS, Scoop on Windows, and language-specific package managers as needed. Where that path is unavailable or incomplete, the setup falls back to system package managers and other installation methods. See Repository Architecture for the setup layers and directory responsibilities, and Platform Notes for FreeBSD and Chimera Linux.

Chezmoi templates drive per-machine configuration. Flags in ~/.config/chezmoi/chezmoi.toml control what gets installed and configured: for example, whether the machine is a work system, has a container runtime, or is headless. Authoring Chezmoi Configuration documents the intent behind those flags. Sensitive files are encrypted with age, with the key bootstrapped from 1Password on first setup if not placed manually.

A note on scope: This is not intended as a starter template, as adopting it wholesale would likely be more complex than most people need.

Setup Entry Points

The setup scripts form a progression from OS installation to day-to-day dotfiles application:

• OS installation (distro-specific, self-contained):
  • os-install: Installs the OS from a live environment. Available for Arch and Chimera Linux.
  • setup-root: Runs as root to create users, install base packages, and prepare for user-level setup. Available for a subset of platforms.
• bootstrap: Installs prerequisites, clones the repository, and initializes chezmoi. Run automatically by the setup scripts below.
• setup-system: Installs system-level packages, Nix, and other prerequisites. Run by a non-root user with sudo/doas access.
• setup / chezmoi apply: Applies dotfiles and runs chezmoi scripts for user-level package installation, application configuration, and shell setup.
• setup-full: Runs setup-system then setup.

Usage

Bootstrap (Optional)

The setup scripts below handle bootstrapping automatically. If you prefer to initialize chezmoi separately — or need to run on a system where the repository isn't yet cloned and git isn't yet available — you can run script/bootstrap standalone:

curl -fsLS https://raw.githubusercontent.com/kergoth/dotfiles/main/script/bootstrap | sh

This installs prerequisites (git, bash, curl, unzip), clones the repository if needed, and installs and initializes chezmoi.

Full Setup

Clone the repository and run setup-full for both system-level setup and dotfiles on a fresh machine:

git clone https://github.com/kergoth/dotfiles .dotfiles
~/.dotfiles/script/setup-full

System Setup

Run this before dotfiles setup if you need system-level packages, Nix, or other prerequisites. This script is run by a non-root user with sudo/doas access. To complete this on macOS, your admin user must have signed into the Mac App Store.

./script/setup-system

On Windows (in PowerShell, not WSL):

./script/setup-system.ps1

Dotfiles Setup

Applies dotfiles and runs chezmoi scripts for user-level package installation and configuration. If system setup is needed, run setup-system first — dotfiles application may depend on tools it installs (e.g. Nix).

If the repository has not yet been cloned:

chezmoi init kergoth/dotfiles
~/.dotfiles/script/setup

If the repository is already cloned:

./script/setup

Edit dotfiles

chezmoi edit --watch ~/.config/zsh/.zshrc

See Authoring Chezmoi Configuration for source resolution, template rendering, and safe inspection before applying changes.

Apply dotfiles changes to the home directory

This step is implicitly done by the setup script. To run it manually, for example, after editing files inside the repository checkout, run this:

chezmoi apply

Update the dotfiles, external files, and home directory packages

./script/update

See Updating External Content for the review-first source and lock workflow.

Local Configuration

These files are not tracked in the repository and allow per-machine customization without modifying managed dotfiles.

Shell (Zsh)

• ~/.zshenv.local — Sourced at the end of .zshenv. Use for early environment variable overrides that need to be set in all shell types (interactive, non-interactive, login, non-login).
• ~/.zprofile.local — Sourced at the end of .zprofile. Use for login-shell-specific overrides such as PATH modifications or environment setup that only applies to login shells.
• ~/.envrc.local — Sourced from the managed ~/.envrc. Use for machine-specific session variables or PATH additions that should participate in direnv and desktop-session environment injection without editing the shared dotfiles.
• ~/.zshrc.local or ~/.localrc — Sourced at the end of .zshrc. Use for interactive shell customizations such as aliases, functions, or prompt tweaks specific to this machine.
• New .zsh files in ~/.config/zsh/.zshrc.d/ — Any .zsh file placed here is automatically sourced by .zshrc. Files are loaded in glob order, with special handling for path.zsh (loaded first), early.zsh, completion.zsh, and final.zsh. Unmanaged files in this directory coexist with chezmoi-managed ones.

Git

• ~/.gitconfig.local — Included by the main git config via [include]. Use for per-machine settings such as user.email, user.signingkey, credential helpers, or work-specific overrides.

Tmux

• ~/.tmux.conf.local — Sourced at the end of the tmux configuration if the file exists. Use for per-machine tmux overrides such as different key bindings, status bar customization, or display settings.

SSH

• Files in ~/.ssh/config.d/ — All files in this directory are included by the SSH config via Include ~/.ssh/config.d/*. Use for per-machine host definitions, jump host configurations, or other SSH settings.

Nix / Home Manager

• ~/.config/home-manager/local.nix — Optionally imported by home.nix if the file exists. Use to install additional Nix packages, enable or disable Home Manager programs, or override settings from the main configuration.

Homebrew (macOS)

• Files in scripts/macos/Brewfile.d/ — Each file in this directory is processed as an additional Brewfile during chezmoi apply. Use to extend the Homebrew package list with machine-specific formulae or casks.
• Files in scripts/macos/Brewfile-admin.d/ — Each file is processed as an additional Brewfile during setup-system. Use to extend the admin Homebrew package list (for packages requiring the shared admin Homebrew prefix).

Desktop Session Environment

• ~/.session-env.local — This file is sourced by the session-env script, which injects its variables into the environment of GUI applications and shell sessions restored via direnv. Use this for machine-local environment variable additions that should be visible to desktop apps and CLI tools alike. Avoid putting secrets here, since it will make them available to every GUI app and CLI tool in the session. For secrets, prefer project-local .envrc, app- or tool-specific login flows, or the platform keychain.

Notes

• .config/git/config is not my main configuration, but is instead a small file which includes my main configuration. This allows for automatic git configuration changes such as vscode's change to credential.manager to be obeyed without it altering my stored git configuration. The downside to this is that these changes will not be highly visible. I may change this back, or keep the including file but track it so the changes are visible.

What's Included

Zsh Plugins

• fzf-tab: Replace zsh's default completion selection menu with fzf.
• nix-zsh-completions: ZSH Completions for Nix.
• powerlevel10k: A Zsh theme.
• zbell: Make Zsh print a bell when long-running commands finish.
• zsh-autosuggestions: Fish-like autosuggestions for zsh.
• zsh-bd: Jump back to a specific directory, without doing cd ../../...
• zsh-completions: Additional completion definitions for Zsh.
• zsh-git-escape-magic: zle tweak for git command line arguments.
• zsh-history-substring-search: ZSH port of Fish history search (up arrow).
• zsh-manydots-magic: zle tweak for emulating ...==../.. etc.
• zsh-nix-shell: Zsh plugin that lets you use zsh in nix-shell shells.
• zsh-syntax-highlighting: Fish shell like syntax highlighting for Zsh.

Fonts

• iA-Fonts: iA Writer Mono, Duo, and Quattro.
• MesloLGS NF: Meslo Nerd Font patched for Powerlevel10k.

Third-Party Scripts

• git-alias (source): Manage git command aliases.
• git-attic: List deleted files from git history with their deletion details.
• git-j (source): Jump between git branches with history tracking.
• git-rebase-chain (source): Rebase a stack of branches from one base to another.
• ifne (source): Run a command only if standard input is not empty. This is a third-party script reimplementation of a tool from moreutils by Joey Hess.
• linux-bundle-clone (source): Clone Linux kernel repositories using CDN-hosted bundles.
• vipe (source): Edit pipe content in your text editor mid-pipeline. This is a third-party script reimplementation of a tool from moreutils by Joey Hess.
• wsl-open: Open files and URLs from WSL in Windows default applications.

System & Desktop Configuration

• Desktop environment: KDE Plasma on Linux and FreeBSD. Conditional: non-headless.
• Display manager: SDDM on Linux and FreeBSD. Conditional: non-headless. init present to enable/start.
• Terminal emulator: kitty on macOS, Linux, and FreeBSD; Windows Terminal on Windows. Conditional: non-headless.
• PDF viewer: Okular on Linux and FreeBSD. Conditional: non-headless.
• App distribution (Flatpak): Flatpak + Flathub on all supported Linux distros. Primary mechanism for GUI app installs where native packages are absent or stale. Conditional: non-headless.
• Core services: mDNS/Avahi, SSH, Bluetooth, and audio stack. PipeWire where applicable. Varies by distro.
• Optional system services: Tailscale, container runtime. Conditional: personal, non-ephemeral for Tailscale. containers flag for container runtime.
• OS exceptions/notes: Service enablement is skipped for WSL2/containers/ephemeral systems.

Desktop Session Environment

Desktop-launched applications on macOS and Linux do not read shell startup files, so they often miss environment variables that are available in terminal sessions. This setup uses session-env to inject a small set of shared variables into the desktop session so GUI apps inherit the same basic context, especially PATH.

In this repo, the managed defaults currently provide PATH and EMAIL.

Terminals launched from the desktop environment inherit those variables automatically, so nothing special is needed there beyond the desktop-session injection itself.

The home-level ~/.envrc is a direnv bridge for shell entry points that bypass the desktop session, especially SSH. In those cases, it sources ~/.session-env so direnv can recreate the same baseline environment in CLI sessions that did not inherit it from the desktop login.

Installed Software

See docs/installed.md for installed software. Changes to the inventory and installation policy are covered by Adding Software.

Additional Docs

• Repository Architecture: Setup progression, directory responsibilities, and the source-to-rendered flow.
• Authoring Chezmoi Configuration: Template variables, source patterns, rendering, runtime directories, and removals.
• Testing and Verification: Automated suites, container setup tests, and the verification matrix.
• Agent Configuration: Shared rules and skills, rendered destinations, and MCP configuration.
• Updating External Content: Review-first source, lock, and container-pin updates.
• Adding Software: Installation policy, platform patterns, inventory updates, and software-specific checks.
• Architectural Decision Records: Significant architectural decisions, documented using the MADR standard.
• Installed Software: Installed software inventory by platform and category.
• As-Needed Software: Software I install occasionally as needed rather than on every machine, with details on how they can be installed.
• Formerly-Used Software: Software I've used in the past but no longer use, with details on why I stopped using them.
• Operating System Installation: Step-by-step instructions for certain operating system installations using the included os-install and setup-root scripts.

Contributing & Support

Questions, comments, feedback, and contributions are always welcome, please open an issue.

See CONTRIBUTING.md for ways to get started contributing to this project and Testing and Verification for the current test entry points.

Please adhere to this project's Code of Conduct and follow The Ethical Source Principles.

License

Distributed under the terms of the Blue Oak Model License 1.0.0 license.