Linux Workspace

Dotfiles & workstation automation for Linux, macOS, WSL. bashrc loads rc/*.sh (ordered by prefix) and adds bin/ to PATH. $LWS points to repo root.

Directory Layout

rc/ — Shell init files, loaded in 0X-name.sh order. Per-tool env setup goes here.
install/ — Idempotent one-off installer scripts (run manually).
bin/ — Scripts auto-added to PATH. New CLI tools go here.
scripts/ — Setup scripts NOT on PATH (git-config, docker fixes, gnome config).
conf/ — Tool configs (vim, WireGuard, WSL).
doc/ — Reference docs, cheatsheets, bookmarks.
functions.sh — Core lib (see below).

Key Helpers (`functions.sh`)

can_run <cmd> — check if command is available
is_slow_init / is_fast_init — check LWS_FAST mode
is_interactive_shell — true when [[ $- == *i* ]]
is_wsl — detect WSL environment
true_false <val> — normalize 1/true/yes to boolean
prepend_path / append_path / prepend_path_try / append_path_try — safe PATH manipulation
source_try <file> — source file if it exists
source_directory_sh <dir> — source all *.sh in a directory
xlog <msg> — debug log (only in interactive + LWS_DEBUG)

Conventions

All new executable bash scripts should use:

#!/usr/bin/env bash

set -E -o errexit -o nounset -o pipefail

Sourced files (rc files, functions.sh) must NOT use set -o errexit — they run inside the user's shell. Add # shellcheck shell=bash at the top instead of a shebang.

Before writing shell code, check functions.sh for existing helper functions and prefer them over raw commands.

Detailed formatting, naming, and syntax rules are in .claude/rules/bash-style.md.

RC files MUST guard slow tools and check availability:

if is_slow_init && can_run pyenv; then
    # initialize pyenv
fi

Installers (install/*.sh) MUST be idempotent — check before installing.

Environment Variables

LWS_FAST=1 — skips slow tools during shell init
LWS_DEBUG=1 — enables debug logging via xlog

Commits

Do not add Co-Authored-By lines to commit messages. Prefer one-line commit messages. Add a longer description only when necessary for better understanding.

2.2 KiB Raw Blame History