Rootbeer

Managing your system

zsh ​

The zsh module lets you describe your shell setup as one Lua table. Rootbeer turns it into the files zsh expects: environment, login profile, interactive settings, aliases, history, completions, and startup commands.

lua
local zsh = require("rootbeer.zsh")

Configure zsh ​

Start with the settings you would normally spread across .zshenv, .zprofile, and .zshrc:

lua
zsh.config({
    keybind_mode = "emacs",
    options = { "CORRECT", "EXTENDED_GLOB" },
    env = {
        EDITOR = "nvim",
        VISUAL = "$EDITOR",
    },
    aliases = {
        g = "git",
        ls = "lsd -l --group-directories-first",
    },
    history = { size = 10000 },
    evals = { "mise activate zsh" },
})

Rootbeer manages your Zsh startup files through ~/.zshenv and makes installed packages available in login shells. Zsh must already be installed; after rb apply, run zsh -l to start it with your settings.

For machine-specific values like work-only aliases or a different EDITOR, use Profiles.

API Reference ​

zsh.config(cfg) ​

Applies the full zsh configuration. Generates ~/.zshenv (bootstrap), <dir>/.zshenv, <dir>/.zprofile, and <dir>/.zshrc from a single config table.

Parameters — cfg: zsh.Config

aliasestable<string, string>optional
Shell aliases defined via alias name="command".
completionszsh.CompletionConfigoptional
Completion system settings.
dirstringoptional
ZDOTDIR path. Defaults to "~/.config/zsh". All zsh files are written here and a bootstrap ~/.zshenv is created to set ZDOTDIR.
envtable<string, string>optional
Environment variables written to .zshenv (available in all shells).
evalsstring[]optional
Commands wrapped in eval "$(cmd)".
extrastring|string[]optional
Raw lines appended as-is to the zshrc.
functionstable<string, string>optional
Shell functions. Keys are names, values are the function body. Supports multi-line [[...]] strings.
historyzsh.HistoryConfigoptional
History settings.
hookstable<string, string|string[]>optional
Zsh hook registrations via add-zsh-hook. Keys are hook names (e.g. "precmd"), values are function names or lists of function names.
keybind_mode"emacs"|"vi"optional
Input mode (set -o emacs or set -o vi).
keybindingstable<string, string>optional
bindkey mappings (e.g. { ["^R"] = "my-widget" }).
optionsstring[]optional
setopt options (e.g. "CORRECT", "EXTENDED_GLOB").
profilezsh.ProfileConfigoptional
Login shell configuration written to .zprofile. Rootbeer's package profile environment is sourced automatically.
promptstringoptional
Raw PS1 prompt string.
sourcesstring[]optional
File paths to source.
variablestable<string, string>optional
Shell variable assignments (not exported).
vcs_infoboolean|zsh.VcsInfoConfigoptional
Enable git branch info in the prompt via vcs_info. When true, uses default format " (%b)". Automatically sets PROMPT_SUBST, adds a precmd hook, and autoloads vcs_info.
widgetsstring[]optional
Function names to register as ZLE widgets via zle -N. The function must be defined in functions.

zsh.CompletionConfig ​

cachestringoptional
Cache directory for completion data.
enablebooleanoptional
Run compinit. Defaults to true.
menu_selectbooleanoptional
Arrow-key menu selection. Defaults to true.
stylestable<string, string>optional
Raw zstyle entries (pattern → value).
vi_navbooleanoptional
Use hjkl for menu navigation. Defaults to false.

zsh.HistoryConfig ​

appendbooleanoptional
Append to history file. Defaults to true.
dedupbooleanoptional
Remove duplicate entries. Defaults to true.
filestringoptional
HISTFILE path. Defaults to $ZDOTDIR/.zsh_history.
ignorestringoptional
HISTIGNORE pattern.
save_sizenumberoptional
SAVEHIST. Defaults to size.
sharebooleanoptional
Share history across sessions. Defaults to true.
sizenumberoptional
HISTSIZE. Defaults to 10000.

zsh.ProfileConfig ​

evalsstring[]optional
Commands wrapped in eval "$(cmd)".
extrastring|string[]optional
Raw lines appended as-is.
path_appendstring[]optional
Directories appended to $PATH.
path_prependstring[]optional
Directories prepended to $PATH.
sourcesstring[]optional
File paths to source.

zsh.VcsInfoConfig ​

check_for_changesbooleanoptional
Enable dirty/staged indicators. Defaults to true.
formatsstringoptional
Format string for vcs_info. Defaults to " (%b)".