ADR-008: Alias System Architecture¶

Status¶

Accepted

Date¶

2026-03-08

Context¶

The dotfiles manage 98 alias files across 30+ categories (git, docker, kubernetes, python, security, etc.). These need to load fast, support per-machine toggling, and work across Zsh, Bash, Fish, and Nushell.

Design questions:

How to organize alias files for maintainability?
How to control which aliases load on which machines?
How to balance startup speed with alias availability?
How to bridge POSIX aliases to non-POSIX shells?

Decision¶

Organization¶

Aliases are organized by tool/domain in .chezmoitemplates/aliases/<category>/<name>.aliases.sh:

aliases/
  git/git.aliases.sh, signing.aliases.sh
  docker/docker.aliases.sh
  kubernetes/kubernetes.aliases.sh
  security/crypto-utils.aliases.sh, ssh-keys.aliases.sh, ...
  default/default.aliases.sh
  ...

Profile Tiers¶

Three profiles control alias scope (set in .chezmoidata.toml):

Profile	Scope	Use Case
`minimal`	Core only, excludes interactive/sudo	Servers, containers
`standard`	All core + selected ecosystem	Laptops, workstations
`full`	Everything including heavy/specialized	Dev machines

Bucket Toggles¶

Per-category flags in .chezmoidata.toml under [aliases.buckets]:

[aliases.buckets]
system = true
svn = false    # disable on machines without SVN

Two-Phase Loading¶

Eager (90-ux-aliases.sh): Core categories loaded at shell startup (~40KB). Includes: archives, cd, clear, configuration, default, diagnostics, disk-usage, editor, git, interactive, installer, mkdir, modern, ps, rsync, sudo, system.
Lazy (91-ux-aliases-lazy.sh): Ecosystem aliases deferred until first prompt via precmd hook. Includes: docker, kubernetes, terraform, gcloud, python, npm, rust, security, etc.

Function Groups (groups.json)¶

Functions use a parallel system with groups.json as a registry:

Groups: api, curl, text, system, files, interactive, nav, security, misc
Lazy-loaded per group on first invocation
Stub functions replaced with real implementations on first call

Consequences¶

Positive¶

Adding aliases is self-service: create a file in the right category
Per-machine customization without forking
Lazy loading keeps startup under 200ms even with 98 alias files
groups.json enables automated bridge generation for Fish/Nushell

Negative¶

Alias definitions wrap in functions (set_default_aliases()) for sourcing safety, adding complexity
Two-phase loading means some aliases aren't available until after first prompt
Profile/bucket system requires understanding .chezmoidata.toml

Trade-offs¶

Chose file-per-category over monolithic alias file for maintainability
Chose runtime extraction for Fish/Nushell over maintaining parallel definitions
Chose lazy loading over compile-time bundling for flexibility