Unix

The OS-neutral base every Unix-like platform role builds on. It owns the ~/.profile.d/ shell framework, the ~/scripts and ~/.versions.d/ directories, and the generic aliases and functions — everything that does not depend on a package manager or a specific shell.

The ubuntu and macos roles import this role as their first task and add only what is OS-specific (package manager, locale, the version alias, and which login files source the framework). You do not list unix in a playbook directly; it comes in through whichever OS role you run.

What it does

• Creates ~/.profile.d/ and configures each login file in unix_profile_files to source ~/.profile.d/init.sh
• Creates ~/.versions.d/ for per-tool version scripts (run by the versions alias)
• Renders the shared unix_env environment (locale plus the XDG base directory defaults) to ~/.profile.d/env.sh, sourced first by init.sh
• Copies helper scripts to ~/scripts and adds it to $PATH
• Installs the generic shell aliases and utility functions
• Hands off to the role matching unix_shell for the shell-specific setup: on bash the bash role removes ~/.bash_profile so it can't shadow ~/.profile, on zsh the zsh role initializes completions

Variables

Variable	Default	Description
unix_shell	shell, or zsh on macOS / bash elsewhere	The host's login shell, resolved from the bare host-level shell variable; picks which shell role runs
unix_profile_files	derived from unix_shell	Login files the framework loader is sourced from: ['~/.zprofile', '~/.zshrc'] when the shell is zsh, ['~/.profile'] otherwise
unix_locale	en_US.UTF-8	LANG / LC_ALL, exported via unix_env on every platform
unix_sudo_timeout	""	Sudo credential cache lifetime in minutes, written as a validated sudoers drop-in scoped to this user (timestamp_timeout + !tty_tickets, shared across terminals) so repeated applies prompt at most once per window. Empty or 0 removes the drop-in and restores the default sudo policy
unix_env	locale + XDG defaults	Shared cross-platform env dict rendered to ~/.profile.d/env.sh and sourced first; ships the locale and the XDG base directory roots, values may be literals or shell expansions
unix_init_header	dotfiles.pro	The boxed banner init.sh prints at the top of every login shell; set your own text to rebrand, or "" to skip it
unix_header_style	heavy	Which unix_header_styles key header delegates to
unix_header_styles	see defaults	Glyph map per style (heavy, light, double, rounded, ascii); each key generates a header-<key> function
unix_list_storage	false	When true, list reports directory storage via du (slow in large trees)
unix_aliases	see defaults	Generic, OS-neutral aliases
unix_functions	see defaults	Shared shell functions (header, keyvalue, list, tab, aliases, functions, commands)

Environment variables

unix_env is the shared, cross-platform environment standard: a dict the role renders to ~/.profile.d/env.sh, which init.sh sources first, before the banner, aliases, functions, and every other fragment, so they can all rely on it. Both the ubuntu and macos roles inherit it, so a variable set here applies on every platform. It defaults to the locale:

unix_env:                  # default: locale (from unix_locale) + the XDG base directory roots
  LANG: "{{ unix_locale }}"
  LC_ALL: "{{ unix_locale }}"
  XDG_CONFIG_HOME: "${XDG_CONFIG_HOME:-$HOME/.config}"
  XDG_DATA_HOME: "${XDG_DATA_HOME:-$HOME/.local/share}"
  XDG_STATE_HOME: "${XDG_STATE_HOME:-$HOME/.local/state}"
  XDG_CACHE_HOME: "${XDG_CACHE_HOME:-$HOME/.cache}"

A value may be a literal or a shell expansion, emitted verbatim inside the quotes, which is exactly how the XDG roots default themselves (${XDG_CONFIG_HOME:-$HOME/.config} keeps a value the session already provides). Override unix_locale to change the locale, drop the XDG_* keys to opt out of XDG, or add keys to unix_env per host.

For environment that belongs to one tool, that role declares its own <role>_env and renders it at the top of its own ~/.profile.d/<role>.sh instead (the googlecloud and wsl roles do this with googlecloud_env / wsl_env); unix_env is for the shared baseline.

Shell framework

This role creates a ~/.profile.d/ directory and configures each login file to source ~/.profile.d/init.sh. Other roles drop scripts into this directory rather than editing .bashrc, .profile, or .zshrc directly. init.sh loads every ~/.profile.d/*.sh once per shell — a guard (DOTPRO_PROFILE_LOADED) makes it safe for macOS, where both ~/.zprofile and ~/.zshrc point at it.

Startup banner

init.sh opens with a boxed banner, then logs each fragment as it loads:

┏━━━━━━━━━━━━━━━━━━┓
┃   dotfiles.pro   ┃
┗━━━━━━━━━━━━━━━━━━┛

  Loading:       ~/.profile.d/aliases.sh
  Loading:       ~/.profile.d/git.sh
  Loading:       ~/.profile.d/ssh.sh

unix_init_header sets the banner text; an empty string skips the banner (the Loading lines stay):

unix_init_header: Initializing...   # default: dotfiles.pro

unix_init_header: Foobar's dotfiles   # default: dotfiles.pro

XDG base directories

unix_env ships the four user-level XDG Base Directory roots at their spec defaults, each applied only when the session has not already set it, so they land in ~/.profile.d/env.sh alongside the locale:

export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"

Tools that honor XDG then keep their config, data, state, and cache out of a cluttered $HOME. XDG_RUNTIME_DIR is deliberately left to the system, which owns it per session. The other roles already write under these roots (~/.config/git, ~/.config/starship.toml, ~/.local/state/dotpro), so the defaults line up with what they assume; relocating a root is an advanced change rather than a default. Drop the four XDG_* keys from unix_env to opt out.

Version tracking

versions (run by system) reads ~/.versions.d/ and reports each tool's current version on every platform. versions-history (run by upgrades) prints the upgrade log that the tool roles write as they bump a tool on Linux. On macOS the tools are installed and upgraded by Homebrew, which keeps its own history (brew outdated), so that log reflects Linux runs while the versions snapshot stays accurate on both.

Aliases

Alias	Command	Description
system	version + versions	Show system and installed software versions
upgrades	versions-history	Show the recorded tool-upgrade history
whereami	pwd	Print current directory
kv	keyvalue	Short alias for the keyvalue function
home	cd ~; list	Go home and list contents
profile	cd ~/.profile.d; list	Go to profile.d and list contents
files	ls -a -p | grep -v /	List files only (no directories)
folders	ls -1 -a -d */ --color=never	List directories only
nameservers	nslookup -type=NS	Look up NS records
mxrecords	nslookup -type=MX	Look up MX records

The version alias itself is OS-specific and provided by the platform role (lsb_release -a on Ubuntu, sw_vers on macOS).

Functions

Function	Description
header	Print a styled box header; delegates to header-<unix_header_style>
header-*	One wrapper per unix_header_styles key (header-heavy, header-light, …), each callable directly
_header	Low-level renderer the header-* wrappers call with their glyph set
keyvalue	Print a dimmed key and its value (alias kv), used by info functions across roles. Takes an optional third argument to color the value — a style name in the starship vocabulary (bold yellow, bright_red, dim cyan, …) or a raw SGR sequence (1;33)
_sgr	Translate a style name to an SGR sequence (e.g. bold yellow → 1;33); used by keyvalue
tab	Set the terminal tab/window title
list	Print a summary of the current directory (location, file count, folder count, contents)
_count	Count files or subfolders in a directory and, when unix_list_storage is set, append the group's du size; used by list
aliases	List defined aliases per group, optionally filtered to one group
functions	List defined functions per group, optionally filtered to one group
commands	Run both aliases and functions

Header styles

header delegates to the wrapper named by unix_header_style (default heavy). Each key in unix_header_styles maps to six glyphs (top-left, horizontal, top-right, vertical, bottom-left, bottom-right) and generates a header-<key> function, so header-light, header-double, header-rounded, and header-ascii are all available directly. Add your own by extending the map.