env/dotfiles
1
0 Fork 0
mirror of https://github.com/prdlk/dotfiles.git synced 2026-11-02 19:32:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(docs): update documentation for tool installation and desktop app changes

Browse Source
This commit is contained in:
Prad Nukala committed 2026-10-16 14:08:32 -04:00
1 parent 31e42d412e
commit fd1fd0cc16
16 files changed
+63 -42
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/chezmoi/config.mdx
+1
View File
@@ -85,6 +85,7 @@ The `[data]` table exposes `.name`, `.email`, and `.role` to every template. che
| `.chezmoi.os` | `run_onchange_before_10-packages.sh.tmpl` | pacman/yay on `linux`, Homebrew on `darwin` |
| `.chezmoi.os` | `run_once_after_30-user-services.sh.tmpl` | systemd user units on `linux` only |
| `.chezmoi.os` | `run_onchange_after_40-post.sh.tmpl` | `fc-cache` on `linux` only |
| `.chezmoi.os`, `.role` | `run_onchange_after_15-tools.sh.tmpl` | strata install on `linux` with role `desktop`/`laptop` |
```ini dot_gitconfig.tmpl
[user]
docs/chezmoi/data.mdx
+10 -8
View File
@@ -7,7 +7,7 @@ Files in `.chezmoidata/` are merged into chezmoi's template data on every run. N
| File | Data key | Consumed by |
| --- | --- | --- |
| `.chezmoidata/packages.yaml` | `.packages` | [`run_onchange_before_10-packages.sh.tmpl`](/chezmoi/scripts#10-packages), [`run_onchange_after_20-gh-extensions.sh.tmpl`](/chezmoi/scripts#20-gh-extensions) |
| `.chezmoidata/packages.yaml` | `.packages` | [`run_onchange_before_10-packages.sh.tmpl`](/chezmoi/scripts#10-packages), [`run_onchange_after_15-tools.sh.tmpl`](/chezmoi/scripts#15-tools), [`run_onchange_after_20-gh-extensions.sh.tmpl`](/chezmoi/scripts#20-gh-extensions) |
| `.chezmoidata/aliases.yaml` | `.aliases` | `dot_config/shell/aliases.sh.tmpl` (bash and zsh) |
| `.chezmoidata/skills.yaml` | `.skills` | [`run_onchange_after_25-skills.sh.tmpl`](/chezmoi/scripts#25-skills) |
@@ -32,17 +32,17 @@ One manifest per platform, plus a `shared` block. Any edit to the file changes t
| Misc CLI | `mise`, `gum`, `glow`, `atuin`, `wget`, `starship`, `zsh-syntax-highlighting` |
| Fonts | `ttf-victor-mono-nerd` |
`packages.arch.aur`, installed with `yay -S --needed --noconfirm` (or `paru`) on every Linux machine: `topgrade`, `portop`.
`packages.arch.aur`, installed with `yay -S --needed --noconfirm` (or `paru`) on every Linux machine: `topgrade`, `portop`. Names some installed package already provides are skipped, and yay is bootstrapped when no helper exists ([10-packages](/chezmoi/scripts#10-packages)).
`packages.arch.desktop`, added only for roles `desktop` and `laptop`:
| Source | Packages |
| --- | --- |
| pacman | `niri`, `xwayland-satellite`, `polkit-gnome`, `uwsm`, `xdg-user-dirs`; Wayland utilities `wl-clipboard`, `cliphist`, `wtype`, `ydotool`, `grim`, `slurp`, `hyprpicker`, `pamixer`, `brightnessctl`, `libnotify`; apps `nautilus`, `imv`, `mpv`, `evince`, `chromium`, `obsidian` |
| AUR | `noctalia-git`, `vicinae-bin`, `beeper-bin`, `fastmail`, `tldraw-offline-bin` |
| `[omarchy]` repo (`packages.arch.desktop.omarchy`, only when `pacman-conf -l` lists that repo) | `herdr`, `flea`, `voxtype-bin`, `xdg-terminal-exec`, `hyprland-preview-share-picker`, `brave-origin-bin`, `claude-desktop`, `1password`, `spotify` |
| pacman | `niri`, `noctalia`, `xwayland-satellite`, `polkit-gnome`, `uwsm`, `xdg-user-dirs`; Wayland utilities `wl-clipboard`, `cliphist`, `wtype`, `ydotool`, `grim`, `slurp`, `hyprpicker`, `pamixer`, `brightnessctl`, `libnotify`; apps `nautilus`, `imv`, `mpv`, `evince`, `chromium`, `obsidian`; strata runtime deps `bubblewrap`, `desktop-file-utils`, `fontconfig`, `gstreamer`, `gst-libav`, `gst-plugins-base`, `gst-plugins-good`, `gtk4`, `gtksourceview5`, `gvfs`, `poppler-glib`, `xdg-utils` |
| AUR (or a sync repo with the same name) | `vicinae-bin`, `tldraw-offline-bin`; desktop apps `beeper-bin`, `fastmail`, `1password`, `brave-origin-bin`, `claude-desktop`, `spotify` |
| `[omarchy]` repo (`packages.arch.desktop.omarchy`, only when `pacman-conf -l` lists that repo) | `herdr`, `flea`, `voxtype-bin`, `xdg-terminal-exec`, `hyprland-preview-share-picker` |
Hyprland, Waybar and the `omarchy-*` commands come with the Omarchy install and are not declared. `niri-dynamic-workspaces` (niri startup) has no package; install it by hand.
Hyprland, Waybar and the `omarchy-*` commands come with the Omarchy install and are not declared. `niri-dynamic-workspaces` (niri startup) has no package; install it by hand. strata (the folder handler) has no package either; [15-tools](/chezmoi/scripts#15-tools) runs its installer.
</Tab>
<Tab title="macOS">
@@ -67,13 +67,15 @@ Compared with Arch, macOS has no `micro`, `diffnav`, `mdfried`, `docker`, `sshfs
| `dlvhdr/gh-dash` | `gh dash`: PR and issue dashboard |
| `meiji163/gh-notify` | `gh notify`: notifications in the terminal |
`packages.shared.cargo` lists `suvadu` and `mandible` (the tmux-palette "mandible" item runs `~/.local/bin/mandible-pick`). [`run_onchange_after_40-post.sh.tmpl`](/chezmoi/scripts#40-post) installs any that `cargo install --list` lacks, and skips the step when `cargo` is absent. `packages.shared.go` is an empty list that no script reads.
`packages.shared.cargo` lists `suvadu` and `mandible` (the tmux-palette "mandible" item runs `~/.local/bin/mandible-pick`). [`run_onchange_after_15-tools.sh.tmpl`](/chezmoi/scripts#15-tools) installs rustup when `cargo` is missing, then any crate `cargo install --list` lacks.
`packages.shared.mise` lists the global mise tools: `ghq`, `bun`, `node`, `uv`, `opencode`, `crush`, and omp as `github:can1357/oh-my-pi` (omp is not in the mise registry, so it uses the GitHub-releases backend, which installs the release binary as `omp`). The same script runs `mise use -g` for each one not yet in the global config (`~/.config/mise/config.toml`, local per machine), then `mise install` on the list. A tool already there keeps its pinned version. topgrade's mise step (`mise upgrade`) updates them.
</Tab>
</Tabs>
:::note
AUR packages need `paru`. Without it the package script prints a warning listing the skipped AUR packages and continues.
AUR packages need `yay` or `paru`. The package script bootstraps `yay` when neither exists; only when that is impossible (running as root with no repo shipping yay) does it print a warning listing the skipped AUR packages and continue.
:::
## aliases.yaml [#aliasesyaml]
docs/chezmoi/index.mdx
+1
View File
@@ -36,6 +36,7 @@ The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/.lo
- .gitmodules
- .chezmoiscripts/
- run_onchange_before_10-packages.sh.tmpl
- run_onchange_after_15-tools.sh.tmpl
- run_onchange_after_20-gh-extensions.sh.tmpl
- run_onchange_after_25-skills.sh.tmpl
- run_once_after_30-user-services.sh.tmpl
docs/chezmoi/scripts.mdx
+26 -9
View File
@@ -3,7 +3,7 @@ title: Apply scripts
description: Every run_ script chezmoi executes during apply, when each one fires, and what it does on each OS and role.
---
Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a directory whose scripts run as if they sat at the source root without creating a matching target directory. Two sit at the repo root. All six are templates and all use `#!/bin/sh` with `set -eu`.
Seven scripts run during `chezmoi apply`. Five live in `.chezmoiscripts/`, a directory whose scripts run as if they sat at the source root without creating a matching target directory. Two sit at the repo root. All seven are templates; `20-gh-extensions` is a fish script, the rest use `#!/bin/sh` with `set -eu` (except `25-skills`, which uses `set -u`).
## Execution order
@@ -12,10 +12,11 @@ Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a direc
<Steps>
<Step title="10-packages (before, onchange)">Install system packages from `packages.yaml`.</Step>
<Step title="Files, symlinks, externals">chezmoi writes the target state.</Step>
<Step title="20-gh-extensions (after, onchange)">Install gh extensions.</Step>
<Step title="15-tools (after, onchange)">rustup and cargo crates, omp, global mise tools, strata on Linux desktops.</Step>
<Step title="20-gh-extensions (after, onchange)">Install gh extensions from a fish session.</Step>
<Step title="25-skills (after, onchange)">Install and prune agent skills.</Step>
<Step title="30-user-services (after, once)">Enable systemd user units on Linux (nirinit, kitty-day-save, projects-sync.timer).</Step>
<Step title="40-post (after, onchange)">bat cache, font cache, cargo installs.</Step>
<Step title="40-post (after, onchange)">bat cache, font cache.</Step>
<Step title="build-bat-cache (after, onchange)">Rebuild bat cache when its theme or config changes.</Step>
<Step title="install-yazi-plugins (after, onchange)">Reinstall yazi plugins when the manifest changes.</Step>
</Steps>
@@ -23,10 +24,11 @@ Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a direc
| Script | Phase | Frequency | Re-run trigger |
| --- | --- | --- | --- |
| `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` | before | onchange | sha256 of `.chezmoidata/packages.yaml`; also the role and OS, which change the rendered package list |
| `.chezmoiscripts/run_onchange_after_15-tools.sh.tmpl` | after | onchange | sha256 of `packages.shared.cargo` and `packages.shared.mise` as JSON; also the OS and role, which add the strata step |
| `.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` | after | onchange | sha256 of `packages.shared.gh_extensions` as JSON |
| `.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` | after | onchange | sha256 of `.skills` as JSON |
| `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` | after | once | Runs once per distinct rendered content |
| `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` | after | onchange | sha256 of `packages.shared.cargo` as JSON; also edits to the script itself or an OS change |
| `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` | after | onchange | Edits to the script itself or an OS change |
| `run_onchange_after_build-bat-cache.sh.tmpl` | after | onchange | sha256 of `dot_config/bat/themes/cyberdream.tmTheme` and `dot_config/bat/config` |
| `run_onchange_after_install-yazi-plugins.sh.tmpl` | after | onchange | sha256 of `~/.config/yazi/package.toml` (empty when the file is absent) |
@@ -48,8 +50,9 @@ Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a direc
1. Uses `pacman` directly when running as root, otherwise `sudo pacman`.
2. `pacman -T` filters each list down to names no installed package provides (so `mise-bin` satisfies `mise`, `yazi-git` satisfies `yazi`), then `pacman -S --needed --noconfirm` installs the rest of `packages.arch.pacman`.
3. For roles `desktop` and `laptop`, the same for `packages.arch.desktop.pacman`, and, when `pacman-conf -l` lists an `omarchy` repo, for `packages.arch.desktop.omarchy`.
4. Builds the AUR list: `packages.arch.desktop.aur` plus `packages.arch.aur` for `desktop`/`laptop`, only `packages.arch.aur` for other roles.
5. If the list is non-empty, runs `yay -S --needed --noconfirm` on it, falling back to `paru`. With neither it prints `warning: yay/paru not found — skipping AUR packages: …` and continues.
4. Builds the AUR list: `packages.arch.desktop.aur` plus `packages.arch.aur` for `desktop`/`laptop`, only `packages.arch.aur` for other roles, then drops every name `pacman -T` says is already provided. Desktop apps already installed from a sync repo (CachyOS, `[omarchy]`) are therefore neither rebuilt nor replaced.
5. If anything is left and neither `yay` nor `paru` is installed, bootstraps `yay`: from a sync repo when `pacman -Si yay` finds one (CachyOS, chaotic-aur), otherwise by building `yay-bin` from the AUR with `makepkg -si` (installs `git` and `base-devel` first; skipped as root, since makepkg refuses root).
6. Runs `yay -S --needed --noconfirm` on the remaining names, falling back to `paru`. yay prefers a sync repo over the AUR when both have the name. If no helper could be bootstrapped it prints `warning: no yay/paru and none could be bootstrapped — skipping AUR packages: …` and continues.
</Tab>
<Tab title="macOS">
@@ -65,13 +68,28 @@ The role is not consulted on macOS.
On any other OS the script renders to just the shebang and comments and does nothing.
## 15-tools [#15-tools]
`.chezmoiscripts/run_onchange_after_15-tools.sh.tmpl` installs the tools that do not come from pacman/Homebrew. It prepends `~/.cargo/bin` to `PATH`, since chezmoi's environment can predate the shell config that adds it. Any failing step aborts the script, so chezmoi keeps the old hash and retries on the next apply.
| Step | Condition | Action |
| --- | --- | --- |
| rustup | `cargo` not on `PATH` | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh -s -- -y --no-modify-path`. `-y` because there is no prompt under chezmoi; `--no-modify-path` because the shell rc files are symlinks into this repo and already source `~/.cargo/env` |
| cargo crates | every OS | `cargo install --locked <crate>` for each `packages.shared.cargo` entry missing from `cargo install --list` |
| mise tools | `mise` installed (warning otherwise) | `mise use -g <tools…>` for each `packages.shared.mise` entry absent from `mise ls --global --json`, then `mise install <tools…>`. A tool already in the global config keeps its pinned version. omp and opencode come from here |
| old omp binary | `~/.local/bin/omp` is a regular file and `mise which omp` resolves | Deletes it: a copy from omp's own installer (`omp.sh/install`) sits ahead of mise's shims on `PATH` |
| strata | Linux, roles `desktop`/`laptop`, no `~/.local/bin/strata` | `curl -fsSL https://raw.githubusercontent.com/lgse/strata/main/install.sh \| bash -s -- --with-desktop-entry --with-file-manager` |
The strata flags install the binary, `~/.local/share/applications/io.github.lgse.Strata.desktop`, and the `org.freedesktop.FileManager1` D-Bus service in `~/.local/share/dbus-1/services` ("Open file location" from other apps). The folder default (`inode/directory`) comes from the managed `~/.config/mimeapps.list` instead of `--with-folder-association`, because `xdg-mime default` would replace that symlink with a plain file. The installer's own dependency step runs `sudo -n pacman`, which fails without cached credentials, so its runtime packages are declared in `packages.arch.desktop.pacman` and are already present when it runs.
## 20-gh-extensions [#20-gh-extensions]
`.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` installs each `packages.shared.gh_extensions` entry on every OS.
`.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` installs each `packages.shared.gh_extensions` entry on every OS. It is a fish script (`#!/usr/bin/env fish`), so fish sources `~/.config/fish` first: `PATH` (mise, `~/.local/bin`, `~/.cargo/bin`) and `GITHUB_TOKEN` (from `gh auth token` in `conf.d/10-env.fish`) are those of a fish session. It runs after every file is applied and after [15-tools](#15-tools), so the fish config and `~/.cargo/env.fish` exist.
- Exits 0 with `warning: gh not installed — skipping extensions` if `gh` is missing.
- Exits 0 with `warning: gh not authenticated — run 'gh auth login', then 'chezmoi apply' again` if `gh auth status` fails.
- Reads `gh extension list`, then runs `gh extension install <repo>` only for extensions not already present.
- Exits 1 listing the failed extensions if any install failed, so the next apply retries.
:::warning
A skipped run still exits 0, so chezmoi records this content as done and a plain re-apply does not retry it, despite what the warning text says. After `gh auth login`, either run `gh extension install` for each entry by hand, or clear chezmoi's onchange state with `chezmoi state delete-bucket --bucket=entryState` and apply again (this re-runs every `run_onchange_` script).
@@ -101,13 +119,12 @@ Other personal automation units (brain-lens, omp-loop, rclone, hermes, voxtype)
## 40-post [#40-post]
`.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` is post-apply housekeeping. It re-runs when the script is edited or `packages.shared.cargo` changes.
`.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` is post-apply housekeeping. It re-runs when the script is edited.
| Step | Condition | Action |
| --- | --- | --- |
| bat cache | `bat` installed | `bat cache --build` |
| Font cache | Linux, `fc-cache` installed | `fc-cache -f` |
| cargo | `cargo` installed | `cargo install --locked <crate>` for each `packages.shared.cargo` entry missing from `cargo install --list` |
Each step ignores failures (`|| true`). tpm is cloned by [`.chezmoiexternal.toml`](/chezmoi/externals-and-ignore#externals), not here.