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.

Chezmoi renders managed source into $HOME, handles encrypted secrets via age, and runs setup scripts as part of the apply process. Home Manager is the preferred user package layer where Nix and nixpkgs fit; Homebrew, Scoop, native packages, Flatpak, language package managers, and pinned external installers fill platform gaps. Machine roles and platform differences are handled through chezmoi templates. See Repository Architecture, Authoring Chezmoi Configuration, and Updating External Content for the details.

This is not intended as a starter template. Adopting it wholesale would likely be more complex than most people need.

Usage

Setup Entry Points

The setup scripts form a progression from system preparation to day-to-day dotfiles application:

• script/bootstrap: installs prerequisites, clones the repository, and initializes chezmoi. The setup scripts below run this automatically when needed.
• script/setup-system: installs system-level packages, Nix, and host prerequisites. Run it as a non-root user with sudo or doas access.
• script/setup: applies dotfiles and runs user-level setup.
• script/setup-full: runs setup-system followed by setup.
• chezmoi apply: manually applies rendered dotfiles after repository edits.
• script/update: reviews available updates, updates pinned external and component versions, applies related dotfiles and Home Manager changes, and commits accepted changes.

Lower-level os-install and setup-root entry points are for raw operating system or distro-specific preparation. See Operating System Installation for those flows.

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 is not yet cloned and git is not yet available, you can run script/bootstrap standalone:

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

This installs prerequisites such as git, bash, curl, and 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 or doas access. To complete this on macOS, your admin user must have signed into the Mac App Store.

./script/setup-system

On Windows, run PowerShell rather than 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, such as 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 implicit in the setup script. To run it manually after editing files inside the repository checkout, run:

chezmoi apply

Update Dotfiles, External Files, and Home Directory Packages

./script/update

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

Supporting Docs

• Inventory: installed software, included external projects, plugins, fonts, scripts, and system or desktop components.
• Customization: local override files and machine-specific configuration paths.
• Repository Architecture: setup layers, directory responsibilities, and source-to-rendered flow.
• Theming: dark/light mode behavior and tool-specific palettes.
• Operating System Installation: raw-OS, WSL, and distro-specific preparation flows.
• Updating External Content: review-first source, lock, and container-pin updates.
• Contributor Guide: contribution workflow and contributor reference links.

Contributing & Support

Questions, comments, feedback, and contributions are welcome. Open an issue to start a discussion.

See CONTRIBUTING.md for ways to get started contributing to this project.

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.