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.

This project is not intended for wholesale adoption, as it adds complexity most people don't need.

Tour

Walk through the daily environment this repository builds. Not every tool is covered here. See the Inventory for the complete list of installed software, plugins, fonts, and system components.

• Font: MesloLGS NF, shared across terminals and editors.
• Color modes: Dark and light are first-class operating modes.
• Dark palette: Dracula.
• Light palette (editors): Alabaster BG.
• Light palette (everything else): Catppuccin Latte.

See Theming for the palette and mode-detection details.

Terminal Workspace

Kitty is the daily terminal, paired with Zsh and a Powerlevel10k prompt. The prompt shows the working directory, Git branch and status, active language environments, and the duration of slow commands. Atuin handles shell command history search.

Near-daily utilities: zoxide, fd, ripgrep, fzf, eza, bat, duf, and dua.

At startup, zsh runs a daily dotfiles check. If updates are available, it pulls them and applies the changes. Vim configuration follows the same pattern weekly. Set DOTFILES_NO_UPDATE or VIM_NO_UPDATE to disable either check.

Editors

Zed is the primary graphical project editor.

Vim is the terminal-native editor and fallback.

Development

Git is the primary source control tool. The configured pager and diff driver add syntax highlighting and color to log and diff output.

A set of aliases extends daily use:

Including the full branch status relative to its upstream:

• st: Short status
• lg: Single-line formatted log
• l: Like lg with a line limit; substantially faster on large repositories such as the kernel
• brstat: Branch status in both directions, including modified commits (via git range-diff)
• last: Time-bounded log. Examples: git last day, git last week
• in: Remote commits not yet in the local branch
• out: Local commits not yet in the remote branch
• please: push --force-with-lease, a safer force push
• au: Stage modifications to tracked files only
• amend: Amend the top commit with staged changes

Tmux maintains background sessions and multi-pane layouts, though most day-to-day splitting happens in Kitty, Vim, or Zed.

Modern Python tooling from Astral is preinstalled across all systems: uv, ruff, and ty.

Pi is the preferred LLM agent harness, chosen for its minimal baseline and extensibility.

Keyboard Configuration

On macOS systems, Karabiner-Elements is used to configure the keyboard, with these as the most important complex modifications:

• Caps Lock to Escape on single press, Control on press and hold.
• Control to Caps Lock on single press, 'Hyper Key' on press and hold.
• Toggle caps_lock by pressing left_shift + right_shift at the same time.

How It Works

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.

Getting Started

On a machine where git is available, clone the repository and run setup:

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

On a fresh machine without git, the bootstrap script installs prerequisites, clones the repository, and initializes chezmoi:

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

Setup

The setup scripts form a progression from system preparation to user-level configuration:

• script/setup-system: installs system-level packages, Nix, and host prerequisites. Requires a non-root user with sudo or doas access. On macOS, your admin user must have signed into the Mac App Store first. On Windows, run script/setup-system.ps1 from PowerShell rather than WSL.
• script/setup: applies dotfiles and runs user-level setup, including package installation via Home Manager and other configured package managers. Run after setup-system if system-level dependencies are needed.
• script/setup-full: runs setup-system followed by setup.
• script/bootstrap: installs prerequisites, clones the repository, and initializes chezmoi. The setup scripts above run this automatically when needed.

Per-distribution os-install and setup-root entry points under script/<distro>/ handle raw operating system and distro-specific preparation. See Operating System Installation for those flows.

Day-to-Day Usage

Edit a dotfile and watch for changes (re-applies on save):

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

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

Apply changes to the home directory manually after editing files in the repository checkout:

chezmoi apply

Run a git pull in the dotfiles repository and then run chezmoi apply on it:

chezmoi update

Review and apply available updates to dotfiles, external files, and software 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.