# 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:

```bash
#!/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:

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