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.

local zsh = require("rootbeer.zsh")

Configure zsh

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

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 writes the generated files into its managed config directory and uses ~/.zshenv as the bootstrap entrypoint.

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.

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)".