~/.bash.d — Modular Bash Configuration

This directory contains modular shell configuration files that are automatically sourced by ~/.bashrc on every new shell session. Instead of maintaining one monolithic .bashrc, each concern lives in its own file — making the setup easier to understand, maintain, and extend.

How It Works

Add the following to the end of your ~/.bashrc:

for file in $HOME/.bash.d/*; do
	[[ -x $file ]] && source $file
done

This iterates over all files in ~/.bash.d/ and sources each one that has the executable bit set. Non-executable files are silently skipped, which provides a simple way to temporarily disable a configuration (just chmod -x the file).

Files are sourced in lexicographic order, so numeric prefixes control the load sequence. This matters because later files may depend on functions or variables defined by earlier ones.

File Naming Convention

Prefix	Purpose	Example
00-	Helper functions (loaded first)	00-path-helper
10-	PATH configuration	10-go-path, 10-rust-path
20-	Build tool settings	20-ninja
30-	Shell/prompt setup	30-starship
50-	Shell completions	50-claude-completion
99-	Credentials (last)	99-gemini, 99-huggingface

Lower numbers load first, so foundational pieces like helper functions (00-) and PATH entries (10-) are available before anything that depends on them.

Current Files

Helpers (00-)

• 00-path-helper — Defines path_append and path_prepend functions that safely add directories to $PATH (checking the directory exists and avoiding duplicates).
• 00-credential-guard — Defines require_private, which warns at shell startup if a credential file has overly permissive permissions (anything beyond owner-only access).
• 00-completion-cache — Defines cached_completion, which caches shell completion scripts to ~/.cache/bash.d/ so they are only regenerated when the tool binary is updated. Used by all 50-*-completion scripts.

PATH (10-)

• 10-bun-path — Adds Bun (JavaScript runtime) binaries to PATH.
• 10-go-path — Sets $GOPATH and adds Go binaries to PATH.
• 10-rust-path — Sets $CARGO_HOME and adds Cargo binaries to PATH.

Build Tools (20-)

• 20-android — Sets $ANDROID_HOME, $JAVA_HOME, and adds Android SDK tools to PATH (only when installed).
• 20-ninja — Configures Ninja as the default CMake generator and enables ccache for C/C++ builds (only when installed).
• 20-oneapi — Lazy-loads the Intel oneAPI environment. Because setvars.sh takes ~1.5 seconds, the full environment is deferred until an Intel tool (icc, icx, ifort, etc.) is first invoked. Call _load_oneapi to trigger it manually.

Prompt (30-)

• 30-starship — Initialises the Starship cross-shell prompt, if installed.

Completions (50-)

All completions (except 50-claude-completion) use cached_completion to avoid subprocess overhead on every shell start. Cache files live in ~/.cache/bash.d/ and are automatically regenerated when the tool binary is updated.

• 50-asdf-completion — Tab completion for the asdf version manager.
• 50-bun-completion — Tab completion for Bun (JavaScript runtime & package manager).
• 50-claude-completion — Tab completion for Claude Code CLI.
• 50-fj-completion — Tab completion for the Forgejo CLI (fj).
• 50-gh-completion — Tab completion for the GitHub CLI (gh).
• 50-podman-completion — Tab completion for Podman (rootless container engine).
• 50-tailscale-completion — Tab completion for Tailscale.
• 50-uv-completion — Tab completion for uv (Python package manager).

Credentials (99-)

• 99-claude.example — Template for Forgejo issue token for Claude Code integrations.
• 99-gemini.example — Template for Gemini API key.
• 99-google.example — Template for Google API key.
• 99-huggingface.example — Template for HuggingFace token ($HF_TOKEN).
• 99-replicate.example — Template for Replicate API token.

Adding a New File

1. Create the file with the appropriate numeric prefix:

   vim ~/.bash.d/50-mytool-completion
   

2. Start the file with the shellcheck directive:

   # shellcheck shell=bash
   

3. Make it executable (required for it to be sourced):

   chmod +x ~/.bash.d/50-mytool-completion
   

4. For credential files, create a .example template and the real file:

   # Create the template (tracked in git)
   cat > ~/.bash.d/99-mytool.example << 'EOF'
   # shellcheck shell=bash
   # Copy to 99-mytool and fill in your token, then: chmod 700 99-mytool
   require_private "${BASH_SOURCE[0]}"
   export MY_SECRET_TOKEN=your-token-here
   EOF
   
   # Create the real file from the template
   cp ~/.bash.d/99-mytool.example ~/.bash.d/99-mytool
   # Edit 99-mytool and fill in your real secret
   chmod 700 ~/.bash.d/99-mytool
   

   Then add 99-mytool to .gitignore.

5. Validate with shellcheck:

   shellcheck ~/.bash.d/50-mytool-completion
   

Security

Credential files (99-*) are excluded from git via .gitignore and are never committed. Each credential has a tracked .example template with placeholder values. To set up credentials:

1. Copy the template: cp 99-foo.example 99-foo
2. Fill in your real secret
3. Restrict permissions: chmod 700 99-foo

Additional protections:

• File permissions — Credential files use mode 700 (owner-only).
• Runtime checks — The require_private helper warns on shell startup if a credential file has been accidentally loosened.
• Never commit real secrets — Only .example templates are tracked in git.