63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This is a modular bash configuration directory (`~/.bash.d/`). Files here are sourced by `~/.bashrc` to set up the shell environment. Each file handles a specific concern (PATH additions, environment variables, shell completions). See `README.md` for a full description of the directory and its contents.
|
||
|
|
|
||
|
|
## File Naming Convention
|
||
|
|
|
||
|
|
Files use numeric prefixes to control load order:
|
||
|
|
- **00-** : Helper functions (loads first — used by other scripts)
|
||
|
|
- **10-** : PATH configuration (foundational)
|
||
|
|
- **20-** : Build tool settings (depends on paths)
|
||
|
|
- **30-** : Shell/prompt setup
|
||
|
|
- **50-** : Shell completions (named `50-<tool>-completion`)
|
||
|
|
- **99-** : Application config, credentials (loads last)
|
||
|
|
|
||
|
|
## Available Helpers (defined in `00-*`)
|
||
|
|
|
||
|
|
Use these in all scripts — do not manipulate `PATH` or check permissions manually:
|
||
|
|
- `path_append <dir>` — add directory to end of `$PATH` (checks existence, prevents duplicates)
|
||
|
|
- `path_prepend <dir>` — add directory to start of `$PATH`
|
||
|
|
- `require_private <file>` — warn if file is group/world-accessible; use in credential files
|
||
|
|
|
||
|
|
## Writing Scripts
|
||
|
|
|
||
|
|
- Every file must start with `# shellcheck shell=bash`
|
||
|
|
- Guard external tools with `command -v <tool> &>/dev/null` before using them
|
||
|
|
- Guard directory-dependent exports with `[[ -d <path> ]]` before exporting
|
||
|
|
- Do not suppress stderr from external scripts — only redirect stdout when needed
|
||
|
|
- Avoid `eval` when `. <(cmd)` (process substitution) works
|
||
|
|
- Prevent `LD_LIBRARY_PATH` duplicates with a `case` guard (see `20-oneapi` for example)
|
||
|
|
|
||
|
|
## Permissions
|
||
|
|
|
||
|
|
- Directory `~/.bash.d/` itself: mode `700`
|
||
|
|
- Regular scripts: mode `755` (executable is **required** for sourcing)
|
||
|
|
- Credential files (`99-*`): mode `700` and must call `require_private "${BASH_SOURCE[0]}"` as the first functional line
|
||
|
|
|
||
|
|
## Validation
|
||
|
|
|
||
|
|
Validate all shell scripts with shellcheck before committing:
|
||
|
|
```bash
|
||
|
|
shellcheck <filename>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Security
|
||
|
|
|
||
|
|
Credential files are **excluded from git** via `.gitignore`. Each has a tracked `.example` template with placeholder values.
|
||
|
|
|
||
|
|
To set up a credential:
|
||
|
|
1. Copy the template: `cp 99-foo.example 99-foo`
|
||
|
|
2. Fill in your real secret
|
||
|
|
3. Restrict permissions: `chmod 700 99-foo`
|
||
|
|
|
||
|
|
When adding new credential files:
|
||
|
|
- Create a `.example` template (mode `644`) tracked in git
|
||
|
|
- Add the real filename to `.gitignore`
|
||
|
|
- Use mode `700` on the real file: `chmod 700 <file>`
|
||
|
|
- Call `require_private "${BASH_SOURCE[0]}"` as the first functional line
|
||
|
|
- **Never commit real secrets**
|
||
|
|
- Be aware that `export`ed tokens are visible to all child processes
|