@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/manual/03-reference/03-environment.md

@@ -1,124 +0,0 @@
----
-render_with_liquid: false
----
-
-# Reference: Environment Variables
-
-All environment variables that affect `.dotfiles` behaviour.
-
-## User-Settable
-
-Variables you can set in your shell to change behaviour.
-
-| Variable | Default | Effect |
-|:---|:---|:---|
-| `DOTFILES_VERBOSE` | unset | Verbose output from `dot` commands |
-| `DOTFILES_NONINTERACTIVE` | unset | Skip interactive prompts (for CI) |
-| `DOTFILES_SILENT` | unset | Suppress non-error output |
-| `DOTFILES_DEBUG` | unset | Print shell-init timing to stderr |
-| `DOTFILES_SOURCE_DIR` | `~/.dotfiles` | Override the source directory |
-| `DOTFILES_WALLPAPER_DIR` | `~/Pictures/Wallpapers` | Custom wallpaper directory |
-| `DOTFILES_CACHE_DIR` | `~/.cache/dotfiles` | Override cache location |
-| `DOTFILES_STATE_DIR` | `~/.local/state/dotfiles` | Override state directory |
-| `DOTFILES_TUNING` | `0` | Enable OS tuning (`dot tune`) |
-| `EDITOR` | `nvim` | Editor used by `dot edit` and `sops` |
-| `PAGER` | `less` | Pager used by `dot manual text` |
-
-## Auto-Populated
-
-Variables the dotfiles set in your shell for tool consumption.
-
-| Variable | Value | Source |
-|:---|:---|:---|
-| `XDG_CONFIG_HOME` | `~/.config` | `dot_zshenv` / `dot_config/fish/conf.d/env.fish.tmpl` |
-| `XDG_CACHE_HOME` | `~/.cache` | ditto |
-| `XDG_DATA_HOME` | `~/.local/share` | ditto |
-| `XDG_STATE_HOME` | `~/.local/state` | ditto |
-| `PATH` | managed order | `dot_config/shell/00-core-paths.sh.tmpl` |
-| `BUN_INSTALL` | `~/.bun` | `env.fish.tmpl` |
-| `PIPX_HOME` | `~/.local/share/pipx` | ditto |
-| `PIPX_BIN_DIR` | `~/.local/bin` | ditto |
-| `BUILDS_TMPDIR` | `/tmp/builds` | `dot_zshenv` (created on shell init) |
-| `CARGO_TARGET_DIR` | (from `~/.cargo/config.toml`) | `target-dir = "/tmp/builds/cargo"` |
-| `GOCACHE` | `/tmp/builds/go-cache` | `mise [env]` |
-| `GOTMPDIR` | `/tmp/builds/go-tmp` | `mise [env]` |
-| `PIP_CACHE_DIR` | `/tmp/builds/pip-cache` | `mise [env]` |
-| `UV_CACHE_DIR` | `/tmp/builds/uv-cache` | `mise [env]` |
-| `ZIG_LOCAL_CACHE_DIR` | `/tmp/builds/zig-cache` | `mise [env]` |
-| `ZIG_GLOBAL_CACHE_DIR` | `/tmp/builds/zig-global-cache` | `mise [env]` |
-| `HOMEBREW_PREFIX` | `/opt/homebrew` or `/usr/local` | `dot_zshenv` (macOS) |
-| `MANPATH` | homebrew-adjusted | ditto |
-| `MISE_EXPERIMENTAL` | `1` | `~/.config/mise/config.toml` |
-| `GITHUB_TOKEN` | from `gh auth token` | `~/.config/mise/config.toml` |
-
-## Read by Tools
-
-Variables set by upstream tools and respected by `.dotfiles`.
-
-| Variable | Used for |
-|:---|:---|
-| `SHELL` | Detect default shell |
-| `TERM` | Terminal capabilities (e.g. `xterm-256color`) |
-| `COLORTERM` | True-color detection (`truecolor`) |
-| `LANG` / `LC_ALL` | Locale (must be UTF-8) |
-| `HOME` | User home directory |
-| `USER` | Username |
-| `SSH_AUTH_SOCK` | ssh-agent socket |
-| `GPG_TTY` | GPG pinentry TTY |
-
-## CI-Specific
-
-Variables relevant in GitHub Actions.
-
-| Variable | Purpose |
-|:---|:---|
-| `CI` | Set to `true` in CI; disables prompts |
-| `GITHUB_ACTIONS` | GHA-specific; enables step summary output |
-| `CHEZMOI_VERSION` | Pinned chezmoi version for CI |
-| `COVERAGE_THRESHOLD` | Executable module-mapping threshold (100 in enforced CI; not line coverage) |
-| `DOTFILES_TEST_MODE` | Skip network-dependent tests |
-
-## Secret-Related
-
-| Variable | Purpose |
-|:---|:---|
-| `SOPS_AGE_KEY_FILE` | Override `~/.config/age/keys.txt` path |
-| `SOPS_AGE_RECIPIENTS` | Override recipients for new encryption |
-| `CHEZMOI_AGE_IDENTITY` | Override age identity for chezmoi decrypt |
-
-> Warning: never set these to values stored in plaintext config. Use a password manager or ephemeral injection.
-
-## Startup Order
-
-Shell-loaded variables follow this precedence (later wins):
-
-1. System defaults (`/etc/environment`, `/etc/profile`)
-2. Homebrew shellenv (macOS)
-3. `~/.zshenv` (earliest user-level file; sets XDG + PATH bootstrap)
-4. `~/.zprofile` or `~/.config/fish/conf.d/*.fish`
-5. `~/.zshrc` or `~/.config/fish/config.fish`
-6. `mise activate` — injects tool-specific env
-7. Per-project `.envrc` via direnv (opt-in)
-
-To debug: `DOTFILES_DEBUG=1 zsh -i -c exit` prints timing for each stage.
-
-## Unsetting
-
-To clean up environment pollution:
-
-```sh
-# Show current dotfiles-set vars
-env | grep -E '^(DOTFILES_|XDG_|BUILDS_)'
-
-# Unset one
-unset DOTFILES_DEBUG
-
-# Reset to defaults (restart shell)
-exec $SHELL -l
-```
-
-## See Also
-
-- [Configuration Files](02-config-files.md)
-- [Feature Flags](05-feature-flags.md)
-- [First Install](../02-tutorials/01-first-install.md)

package/docs/manual/03-reference/04-templates.md

@@ -1,190 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Reference: Template Variables
-
-Every variable available to chezmoi templates (`.tmpl` files).
-
-## From `.chezmoidata.toml`
-
-Flat top-level keys:
-
-| Variable | Type | Example |
-|:---|:---|:---|
-| `.dotfiles_version` | string | `"0.2.501"` |
-| `.theme` | string | `"tahoe-dark"` |
-| `.machine` | string | `"macbook-t2"` |
-| `.profile` | string | `"laptop"` |
-| `.default_shell` | string | `"fish"` |
-| `.terminal_font_family` | string | `"JetBrainsMono Nerd Font"` |
-| `.terminal_font_size` | int | `12` |
-| `.name` | string | `"Your Name"` |
-| `.email` | string | `"you@example.com"` |
-
-## From `.chezmoidata/themes.toml`
-
-```go
-{{- $t := index .themes .theme }}
-{{ $t.mode }}              // "dark" or "light"
-{{ $t.family }}            // "tahoe"
-{{ $t.macos_accent }}      // 4 (integer)
-{{ $t.term.bg }}           // "#121430"
-{{ $t.term.fg }}           // "#d4d8ec"
-{{ $t.term.c0 }} .. {{ $t.term.c15 }}   // ANSI 0-15
-{{ $t.ui.accent }}         // "#3951b1"
-{{ $t.ui.accent_text }}    // "#ffffff"
-{{ $t.ui.panel }}
-{{ $t.ui.border }}
-{{ $t.app.nvim }}          // "catppuccin"
-{{ $t.app.starship_palette }}
-```
-
-## From `.chezmoidata/hardware.toml`
-
-```go
-{{- $hw := index .hardware .machine }}
-{{ $hw.display_scale }}    // 2.0
-{{ $hw.kbd_layout }}       // "qwerty"
-{{ $hw.modifier_mode }}    // "left-cmd-control"
-{{ $hw.perf_profile }}     // "laptop"
-{{ $hw.wm }}               // "aerospace"
-{{ $hw.features.touchid }} // bool
-```
-
-## From Feature Flags
-
-```go
-{{- $f := mergeOverwrite .features $hw.features }}
-{{ if $f.dms }}
-# Dank Material Shell-specific config
-{{ end }}
-
-{{ if $f.niri }}
-# Niri WM config
-{{ end }}
-```
-
-## Built-in Chezmoi Variables
-
-```go
-{{ .chezmoi.os }}                // "darwin" | "linux" | "windows"
-{{ .chezmoi.arch }}              // "amd64" | "arm64"
-{{ .chezmoi.kernel }}            // "Darwin" | "Linux"
-{{ .chezmoi.kernel.ostype }}     // "darwin24" etc
-{{ .chezmoi.hostname }}          // host machine hostname
-{{ .chezmoi.username }}          // current user
-{{ .chezmoi.homeDir }}           // $HOME
-{{ .chezmoi.sourceDir }}         // ~/.dotfiles
-{{ .chezmoi.workingTree }}       // git working tree root
-{{ .chezmoi.executable }}        // chezmoi binary path
-{{ .chezmoi.osRelease }}         // Linux /etc/os-release data
-```
-
-## Built-in Chezmoi Functions
-
-```go
-{{ exec "command" | trim }}
-{{ output "hostname" }}
-{{ include "path/to/file" }}
-{{ decrypt "path/to/file.age" }}
-{{ sopsDecrypt "path/to/file.sops.yaml" | fromYaml }}
-{{ joinPath "a" "b" }}
-{{ stat "/path" }}
-{{ ioreg ".." ".." }}             // macOS only
-{{ lookPath "command" }}           // returns path or empty
-```
-
-## Helper Templates (in `.chezmoitemplates/`)
-
-Reusable partials included via:
-
-```go
-{{ template "paths/00-default.paths.sh" . }}
-{{ template "aliases/cd.aliases.sh" . }}
-{{ template "functions/cdls.sh" . }}
-```
-
-Available partials:
-
-- `paths/00-default.paths.sh` — canonical PATH construction
-- `paths/05-pipx.paths.sh` — pipx + ~/.local/bin
-- `paths/99-custom.paths.sh` — user-appended paths
-- `aliases/*.aliases.sh` — per-domain alias sets
-- `functions/*.sh` — reusable shell functions
-
-## Example: Using Theme in Ghostty Config
-
-```go
-{{- /* dot_config/ghostty/config.tmpl */ -}}
-{{- $t := index .themes .theme -}}
-
-font-family = "{{ .terminal_font_family }}"
-font-size = {{ .terminal_font_size }}
-
-background = {{ $t.term.bg }}
-foreground = {{ $t.term.fg }}
-cursor-color = {{ $t.term.cursor }}
-
-palette = 0={{ $t.term.c0 }}
-palette = 1={{ $t.term.c1 }}
-palette = 2={{ $t.term.c2 }}
-# ... through 15
-
-{{- if eq .chezmoi.os "darwin" }}
-macos-titlebar-style = transparent
-{{- end }}
-```
-
-## Example: Platform × Preset
-
-```go
-{{- $hw := index .hardware .machine -}}
-
-{{- if and (eq .chezmoi.os "darwin") (eq $hw.wm "aerospace") }}
-# macOS AeroSpace config
-include = ["aerospace-macos.toml"]
-{{- else if and (eq .chezmoi.os "linux") (eq $hw.wm "niri") }}
-# Linux Niri config
-include = ["niri.kdl"]
-{{- end }}
-
-# DPI-aware sizing
-font-size = {{ mul 8 $hw.display_scale | int }}
-```
-
-## Template Testing
-
-Render a template without applying:
-
-```sh
-chezmoi execute-template < dot_config/ghostty/config.tmpl
-```
-
-Or test an expression:
-
-```sh
-chezmoi execute-template '{{ .chezmoi.os }}'
-# darwin
-
-chezmoi execute-template '{{- $t := index .themes .theme -}}{{ $t.term.bg }}'
-# #121430
-```
-
-## Validation in CI
-
-Every push to main runs:
-
-```sh
-chezmoi apply --dry-run
-```
-
-If any template fails to render, the build breaks before merge.
-
-## See Also
-
-- [Chezmoi template reference](https://www.chezmoi.io/reference/templates/)
-- [Configuration Files](02-config-files.md)
-- [Create a Profile tutorial](../02-tutorials/03-create-profile.md)
-{% endraw %}

package/docs/manual/03-reference/05-feature-flags.md

@@ -1,187 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Reference: Feature Flags
-
-Feature flags toggle optional subsystems. Set in `.chezmoidata.toml`, override per-preset in `.chezmoidata/hardware.toml`.
-
-## Global Flags (`.chezmoidata.toml`)
-
-```toml
-[features]
-alias_wrapper = false      # Wrap selected aliases with safer defaults
-dms           = true       # Dank Material Shell (Niri desktop)
-zellij        = false      # Zellij terminal multiplexer config
-linux_desktop = false      # Linux-specific desktop configs
-niri          = false      # Niri window manager
-waybar        = false      # Waybar status bar
-fuzzel        = false      # Fuzzel application launcher (Wayland)
-mako          = false      # Mako notification daemon (Wayland)
-foot          = false      # Foot terminal emulator (Wayland)
-kanshi        = false      # Kanshi monitor profile manager (Wayland)
-touch         = false      # Touchscreen-friendly tweaks (Surface, etc.)
-t2            = false      # Apple T2 hardware-specific tweaks
-surface       = false      # Microsoft Surface hardware-specific tweaks
-```
-
-## Per-Preset Overrides (`.chezmoidata/hardware.toml`)
-
-```toml
-[hardware.surface-pro.features]
-niri = true
-waybar = true
-dms = true                 # overrides .chezmoidata.toml default
-```
-
-The effective value is `mergeOverwrite` of global + preset features.
-
-## Flag Catalogue
-
-### `dms` — Dank Material Shell
-
-When `true`:
-
-- Configures DMS IPC for theme sync
-- Enables Quickshell templates
-- Sets up per-monitor wallpaper via `dms ipc wallpaper`
-
-Requires: Niri + Quickshell + DMS installed.
-
-### `linux_desktop` — Linux Desktop Configs
-
-When `true`:
-
-- Enables GTK 3/4 theme generation from `themes.toml`
-- Configures `gsettings color-scheme` behaviour
-- Generates desktop file entries for installed tools
-
-No effect on macOS.
-
-### `niri` — Niri Window Manager
-
-When `true`:
-
-- Generates `~/.config/niri/config.kdl`
-- Enables Niri keybindings from `keybinds.toml`
-- Configures workspace rules per preset
-
-Requires: Niri installed.
-
-### `waybar` — Waybar Status Bar
-
-When `true`:
-
-- Generates `~/.config/waybar/config.jsonc` + `style.css`
-- Hooks into theme switching via `dot-theme-sync`
-
-Requires: Waybar installed.
-
-### `alias_wrapper` — Safer Alias Defaults
-
-When `true`, opt-in wrappers replace selected aliases with confirmation-prompt
-variants (e.g., `rm -i`, `mv -i`). Default `false` for power-user ergonomics.
-
-### `zellij` — Zellij Terminal Multiplexer
-
-When `true`:
-
-- Generates `~/.config/zellij/config.kdl` from the active theme
-- Wires the `dot mux` alias to launch a profile-aware session
-
-Requires: Zellij installed.
-
-### `fuzzel` — Fuzzel Application Launcher (Wayland)
-
-When `true`, generates `~/.config/fuzzel/fuzzel.ini` using the active theme.
-Requires: Fuzzel installed (Wayland-only). No effect on macOS.
-
-### `mako` — Mako Notification Daemon (Wayland)
-
-When `true`, generates `~/.config/mako/config` with theme-derived colors.
-Requires: Mako installed (Wayland-only). No effect on macOS.
-
-### `foot` — Foot Terminal Emulator (Wayland)
-
-When `true`, generates `~/.config/foot/foot.ini` from `themes.toml`.
-Requires: Foot installed (Wayland-only). No effect on macOS.
-
-### `kanshi` — Kanshi Monitor Profile Manager (Wayland)
-
-When `true`, generates `~/.config/kanshi/config` with per-host monitor layouts.
-Requires: Kanshi installed (Wayland-only). No effect on macOS.
-
-### `touch` — Touchscreen-Friendly Tweaks
-
-When `true`, enables larger UI scaling and touch-friendly input mappings.
-Typically combined with `surface` for Microsoft Surface devices.
-
-### `t2` — Apple T2 Hardware Tweaks
-
-When `true`, enables `t2linux` kernel-module hints, audio routing fixes, and
-Touch-Bar utilities for Intel Macs with the T2 chip on Linux. Set by the
-`macbook-t2` hardware preset in `.chezmoidata/hardware.toml`.
-
-### `surface` — Microsoft Surface Hardware Tweaks
-
-When `true`, enables `linux-surface` kernel parameters, touchpad gestures, and
-pen-input mappings. Set by the `surface-pro` hardware preset.
-
-## Using a Flag in a Template
-
-```go
-{{- $hw := index .hardware .machine }}
-{{- $f := mergeOverwrite .features $hw.features }}
-
-{{ if $f.niri }}
-# Niri-specific config
-{{ end }}
-```
-
-## Checking Active Flags
-
-```sh
-chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{- $f := mergeOverwrite .features $hw.features -}}{{ $f | toToml }}'
-```
-
-## Adding a New Flag
-
-1. Add to `.chezmoidata.toml`:
-
-   ```toml
-   [features]
-   my_new_flag = false
-   ```
-
-2. (Optional) Set per preset:
-
-   ```toml
-   [hardware.macbook-t2.features]
-   my_new_flag = true
-   ```
-
-3. Use in templates:
-
-   ```go
-   {{ if $f.my_new_flag }}
-   # conditional config
-   {{ end }}
-   ```
-
-4. Document here with the flag's purpose and requirements
-
-## Flag Deprecation
-
-Flags can be deprecated without breaking existing hosts. The deprecation process:
-
-1. Mark the flag as deprecated in this document
-2. Leave the flag evaluation in place for one release
-3. In the subsequent release, remove the template branches and the flag definition
-4. Users who had the flag set will see it ignored — no errors
-
-## See Also
-
-- [Configuration Files](02-config-files.md)
-- [Create a Profile](../02-tutorials/03-create-profile.md)
-{% endraw %}