Skip to content

config.md

Latest commit

 

History

History
249 lines (209 loc) · 10.8 KB

config.md

File metadata and controls

249 lines (209 loc) · 10.8 KB
Raw

hollow.config

Read, write, and reload configuration. The runtime resolves a base config (the shipped conf/init.lua) and an override config (%APPDATA%\hollow\init.lua on Windows, $XDG_CONFIG_HOME/hollow/init.lua elsewhere) at startup and on reload.

For the conceptual model see Configuration. For the LuaLS schema see types/hollow.lua (HollowConfig, HollowDomainConfig, HollowSshDomainConfig).

Functions

hollow.config.set(opts)        -- merge opts into the current config
hollow.config.get(key)         -- read a value
hollow.config.snapshot()       -- a deep copy of the merged config
hollow.config.reload()         -- re-run base + override and reapply

hollow.config.populate_wsl_domains()  -- Windows: add a domain per installed WSL distro

set is a merge, not a replace: nested tables merge key-by-key, last writer wins for scalars. reload() is what <leader>uu is bound to in the shipped base config.

Top-level keys

Key Type Notes
fonts table Font family, size, hinting, smoothing, embolden, fallbacks
theme string or table Built-in theme name or inline spec
scrollback integer Lines of history
cols, rows integer Initial grid size
padding integer Cell padding in pixels
window_title, window_width, window_height string, integer Window geometry
window_titlebar_show boolean Show the OS title bar
top_bar_mode "always" | "tabs" When to show the top bar
top_bar_height, top_bar_bg integer, color Top bar geometry
bottom_bar_show, bottom_bar_height, bottom_bar_bg, bottom_bar_draw_status mixed Bottom bar
scrollbar table Scrollbar config
hyperlinks table OSC 8 hyperlink config
cursor table Cursor style, blink
unfocused_pane table Cursor and dim style for unfocused panes
shell string or string[] Default shell (when no domain is set)
default_domain string Domain used for new tabs / panes
domains table<string, string or table> Domain table
env table<string, string> Extra env vars injected into guests
workspace table auto_bootstrap, default_layout
max_fps, idle_max_fps integer Renderer framerate cap
vsync boolean Renderer vsync
synchronized_output boolean Hold last frame during DEC mode 2026 (default true)
alternate_screen_resize_nudge boolean Delayed resize cycle on alternate-screen entry (default true)
hide_mouse_cursor_when_typing boolean Hide OS mouse cursor during keyboard input
backend string Primary renderer backend ("sokol")
command_timing boolean On-screen command timing overlay
load_default_keymaps boolean Register shipped keymaps (default true)
debug_overlay, debug_terminal_trace boolean Debug overlays
bell table Visual bell config

Fonts

hollow.config.set({
  fonts = {
    family = "Cascadia Mono",
    size = 14,
    line_height = 0.95,
    smoothing = "grayscale",   -- or "subpixel"
    hinting = "light",         -- or "none", "normal"
    ligatures = true,
    embolden = 0.33,           -- global default
    regular_embolden = 0.0,    -- per-face overrides
    bold_embolden = 0.0,
    italic_embolden = 0.5,
    bold_italic_embolden = 0.0,
    fallbacks = { "Segoe UI Symbol", "Noto Sans Symbols 2" },
  },
})

Scrollbar

hollow.config.set({
  scrollbar = {
    enabled = true,
    width = 12,
    min_thumb_size = 24,
    margin = 2,
    jump_to_click = true,
    track = "#000000",
    thumb = "#7e9cd8",
    thumb_hover = "#a0bfee",
    thumb_active = "#c0d8ff",
    border = "#000000",
  },
})

Hyperlinks

hollow.config.set({
  hyperlinks = {
    enabled = true,
    shift_click_only = true,
    match_www = true,
    prefixes = "https:// http:// file:// ftp:// mailto:",
    delimiters = " \t\r\n\"'<>[]{}|\\^`",
    trim_leading = "([<{'\"",
    trim_trailing = ".,;:!?)]}",
  },
})

Cursor

hollow.config.set({
  cursor = {
    style = "block",        -- "block" | "bar" | "underline" | "block_hollow"
    blink = true,
    blink_rate = 500,
  },
})

Mouse Cursor

This option defaults to true. Set it to false to keep the OS mouse cursor visible while typing. Mouse movement shows the cursor again.

hollow.config.set({ hide_mouse_cursor_when_typing = true })

Bell

hollow.config.set({
  bell = {
    visual = true,
    audible = false,         -- reserved, currently a no-op
    visual_duration_ms = 150,
    visual_color = "#ffcc88",
    visual_alpha = 80,       -- 0..255
  },
})

Domains

A domain is a named shell the runtime can spawn. domains maps a domain name to either a shell string or a table with per-domain options.

hollow.config.set({
  default_domain = "UbuntuWSL",
  domains = {
    pwsh       = { shell = "pwsh.exe" },
    powershell = { shell = "powershell.exe" },
    cmd        = { shell = "cmd.exe" },
    wsl        = { shell = "C:\\Windows\\System32\\wsl.exe",
                   default_cwd = "/home/me" },
    unix       = { shell = "/bin/zsh" },
  },
})

WSL domains

The shipped base config calls hollow.config.populate_wsl_domains() on Windows. It enumerates wsl.exe -l and creates one domain per distro named {distro}WSL, plus a default wsl domain.

You can also address a specific distro by hand:

hollow.config.set({
  domains = {
    wsl = { shell = "wsl.exe -d Ubuntu" },
  },
})

SSH domains

hollow.config.set({
  domains = {
    devbox = {
      ssh = {
        alias = "devbox",            -- SSH config host alias
        host = "10.0.0.8",           -- or use `host` directly
        user = "root",
        backend = "UbuntuWSL",             -- "native" or "wsl"
        reuse = "auto",              -- "none" or "auto"
      },
    },
  },
})
  • alias uses an SSH config host directly when host is not set.
  • host makes Hollow prefer user@host.
  • backend = "wsl" launches the SSH client through wsl.exe. This is the practical choice on Windows when you want Linux-side SSH config and agent behaviour.
  • reuse = "auto" enables OpenSSH multiplexing flags for WSL/Linux-backed SSH domains. Native Windows OpenSSH falls back safely without extra flags.

See WSL → WSL workflow patterns.

Workspace bootstrap

hollow.config.set({
  workspace = {
    auto_bootstrap = "always",   -- or "never"
    default_layout = "default",  -- ~/.config/hollow/layouts/default.json
  },
})

When auto_bootstrap = "always", Hollow checks for .hollow/workspace.json rooted at the active pane cwd first, then falls back to workspace.default_layout. See hollow.workspace.

Snapshot

local snap = hollow.config.snapshot()
print(hollow.json.encode(snap, { indent = true }))

snapshot() returns a deep copy. Use it for debugging or for code that needs to read config without reflecting later writes.

See also