Linux Workspace

Dotfiles & workstation automation for Linux, macOS, WSL. bashrc sources rc/*.sh alphabetically and adds bin/ to PATH. $LWS points to repo root.

Directory Layout

rc/ — Shell init files, sourced alphabetically. Use a 0X- prefix only when a file must load before others. Per-tool env setup goes here.
rc.available/ — Archived rc files, not loaded. Do not edit or reference.
rc.fish/ — Fish init (loaded by fishrc). Bash changes are not mirrored there automatically.
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
is_ssh_session — true when logged in over SSH
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.

Verification

After editing shell code, run:

shellcheck <file> — fix new warnings in code you touched
bash -n <file> — syntax check
LWS_DEBUG=1 bash -i -c exit — after rc/ or functions.sh changes; shell must start without errors

macOS Compatibility

Code must also run on macOS with BSD userland. Avoid GNU-only flags (sed -i without a suffix argument, date -d, readlink -f, grep -P), or branch on uname.

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.
Commit messages must be in English.
Prefer one-line commit messages. Add a longer description only when necessary for better understanding.

3.0 KiB Raw Blame History