zsh

Declarative zsh configuration. Describe your entire shell setup — environment variables, login profile, options, aliases, prompt, history, completions — as a single Lua table and rootbeer generates all the zsh files for you: ~/.zshenv (bootstrap), <dir>/.zshenv, <dir>/.zprofile, and <dir>/.zshrc.

local zsh = require("rootbeer.zsh")

Example

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" },
})

For per-machine overrides, see Multi-Device Config. For the conditionals pattern, see Core Concepts.

API Reference

config(cfg)

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

aliasestable<string, string>optional

Shell aliases defined via alias name="command".

completions(zsh.CompletionConfig)optional

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

extra(string|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.

history(zsh.HistoryConfig)optional

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

profile(zsh.ProfileConfig)optional

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_info(boolean|zsh.VcsInfoConfig)optional

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

extra(string|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)".