🐚 Bash Configuration

Modern, modular Bash configuration mirroring the Zsh setup for consistency across shells

📁 Architecture

~/.bash_profile              # Login shell entry point (sources .bashrc)
~/.bashrc                    # Main configuration entry point
~/.bash/                     # Modular configuration directory
  ├── 00-env.bash           # Environment & theme configurations
  ├── 01-path.bash          # PATH management with lazy loading
  ├── 10-aliases.bash       # Command aliases & shortcuts
  ├── 20-functions.bash     # Custom shell functions
  └── 99-integrations.bash  # External tool integrations

Note for macOS users: On macOS, terminals start login shells which read .bash_profile, not .bashrc. The .bash_profile simply sources .bashrc to unify behavior across platforms.

🎯 Why Bash?

While Zsh is the primary shell, Bash configuration is maintained for:

🖥️ Minimal servers - When only Bash is available
🐳 Containers - Docker/Kubernetes debugging
🔧 Recovery mode - System troubleshooting
🌐 Universal compatibility - Works everywhere

🎨 Theme: Catppuccin Mocha / Snazzy

Platform-specific theming with automatic detection:

Platform	Theme	Colors
🍎 macOS	Catppuccin Mocha	Purple/Pink
🐧 Linux	Snazzy	Cyan/Yellow
🍓 Raspberry Pi	Snazzy	Cyan/Yellow

🚀 Modern CLI Tools

Same modern tool aliases as Zsh:

Traditional	Modern	Alias
`ls`	eza	`ls`, `ll`, `l`, `lt`
`cat`	bat	`cat`
`cd`	zoxide	`z`
`vim`	neovim	`vim`
`curl`	xh	`http`

📝 File-by-File Documentation

~/.bash_profile

Purpose: Login shell entry point (macOS terminal sessions)

Features:

Sources ~/.bashrc for all configuration
Required on macOS where terminals start login shells

# Source .bashrc for interactive shell configuration
if [[ -f "${HOME}/.bashrc" ]]; then
  source "${HOME}/.bashrc"
fi

~/.bashrc

Purpose: Main configuration entry point

Features:

Interactive shell detection
Shell options (histappend, autocd, globstar, etc.)
Modular config loading from ~/.bash/
Starship prompt initialization

Shell Options:

shopt -s histappend       # Append to history
shopt -s checkwinsize     # Update terminal size
shopt -s cdspell          # Correct cd typos
shopt -s autocd           # cd without typing cd
shopt -s globstar         # ** recursive glob
shopt -s nocaseglob       # Case-insensitive glob

00-env.bash

Purpose: Core environment variables, platform detection, and cache helper

🚀 `_cache_eval()` Helper

Caches shell-init command output for 24 hours with automatic invalidation:

_cache_eval "name" "command"  # Caches 'command' output to ~/.cache/shell/name.bash

Features:

Invalidates cache when binary path changes (e.g., Homebrew → Pacman, install → uninstall)
Tracks binary path in .meta file
Falls back to live eval if cache is stale or missing
Used for: Starship, Zoxide, Atuin, Carapace initialization

Sections:

🌍 Platform Detection

IS_MACOS=true/false
IS_LINUX=true/false
IS_RPI=true/false
IS_UBUNTU=true/false
IS_FEDORA=true/false
IS_ARCH=true/false
PLATFORM=macos/linux/rpi/ubuntu/debian/fedora/arch/omarchy/toolbox
MACHINE_PROFILE=mac-personal/mac-pro/ubuntu-desktop/ubuntu-server/rpi/arch-desktop/arch-server/omarchy/fedora-desktop/fedora-server/fedora-atomic/debian/toolbox

🏠 Hostname Icons (Starship)

macOS:       ⌘
bbh-network: 🌐
omv-*:       🐟
Other Linux: 🍓

🌐 Locale

LANG=en_US.UTF-8
LC_ALL=en_US.UTF-8

📜 History

HISTFILE=~/.bash_history
HISTSIZE=50000
HISTFILESIZE=50000
HISTCONTROL=ignoreboth:erasedups
HISTIGNORE="ls:cd:exit:clear:history"

🎨 Theme Configuration

macOS (Catppuccin Mocha):

STARSHIP_CONFIG=~/.config/starship/starship-desktop.toml
FZF_DEFAULT_OPTS="--color=bg+:#313244,bg:#1e1e2e..."
BAT_THEME="Catppuccin Mocha"
LS_COLORS=$(vivid generate catppuccin-mocha)

Linux/RPi (Snazzy):

STARSHIP_CONFIG=~/.config/starship/starship-ssh.toml
FZF_DEFAULT_OPTS="--color=bg+:#3a3d4d,bg:#282a36..."
BAT_THEME="ansi"
LS_COLORS=$(vivid generate snazzy)

01-path.bash

Purpose: PATH management with performance optimization

Helper Functions:

path_prepend "/path"  # Add to beginning if exists
path_append "/path"   # Add to end if exists

PATH Priority (highest first):

~/.local/bin
~/.cargo/bin
~/.antigravity/antigravity/bin (macOS)
~/.jenv/bin (macOS)
~/.rbenv/shims (macOS)
~/.tmuxifier/bin (macOS)
System paths
/opt/X11/bin, /Library/TeX/texbin (macOS)
~/.lmstudio/bin

⚡ Lazy Loading (macOS):

# pyenv loads only when first called
pyenv() {
  unset -f pyenv
  eval "$(command pyenv init -)"
  pyenv "$@"
}

# jenv loads only when first called  
jenv() {
  unset -f jenv
  eval "$(command jenv init -)"
  jenv "$@"
}

10-aliases.bash

Purpose: Command shortcuts (identical to Zsh)

🔧 Configuration

bashconfig    # Edit ~/.bashrc with nvim

🚀 Modern Replacements

vim='nvim'
cat='bat'
http='xh'
la='tree'

📂 Eza (ls replacement)

ls='eza --color=always --icons'
ll='eza -l --color=always --icons --git -a'
l='eza -l --icons --git -a'
lt='eza --tree --level=2 --long --icons --git'
ltree='eza --tree --level=2 --icons --git'
zl='eza -lagX --icons --color=always'

📁 Navigation

..      # cd ..
...     # cd ../..
....    # cd ../../..
.....   # cd ../../../..
......  # cd ../../../../..
iclouddrive  # cd to iCloud Drive

🔀 Git

gc='git commit -m'
gca='git commit -a -m'
gp='git push origin HEAD'
gpu='git pull origin'
gst='git status'
glog='git log --graph --pretty=...'
gdiff='git diff'
gco='git checkout'
gb='git branch'
gba='git branch -a'
gadd='git add'
ga='git add -p'
gcoall='git checkout -- .'
gr='git remote'
gre='git reset'

🐳 Docker

dco='docker compose'
dps='docker ps'
dpa='docker ps -a'
dl='docker ps -l -q'
dx='docker exec -it'

☸️ Kubernetes

k='kubectl'
ka='kubectl apply -f'
kg='kubectl get'
kd='kubectl describe'
kdel='kubectl delete'
kl='kubectl logs -f'
kgpo='kubectl get pod'
kgd='kubectl get deployments'
kc='kubectx'
kns='kubens'
ke='kubectl exec -it'
kcns='kubectl config set-context --current --namespace'

🔐 Security & Pentesting

gobust='gobuster dir --wordlist ~/security/wordlists/diccnoext.txt --wildcard --url'
dirsearch='python dirsearch.py -w db/dicc.txt -b -u'
massdns='~/hacking/tools/massdns/bin/massdns -r ...'
server='python -m http.server 4445'
tunnel='ngrok http 4445'
fuzz='ffuf -w ~/hacking/SecLists/content_discovery_all.txt -mc all -u'
nm='nmap -sC -sV -oN nmap'

🔐 SSH

sshpw='ssh -o PreferredAuthentications=password'

20-functions.bash

Purpose: Custom shell functions

📂 cx - Change directory and list

cx /path/to/dir  # cd + automatic eza listing

🔍 fcd - Fuzzy directory navigation

fcd  # Interactive FZF directory picker, then cd

📋 f - Copy file path with FZF

f  # Select file with FZF, copy path to clipboard

✏️ fv - Open file in nvim with FZF

fv  # Select file with FZF, open in neovim

🔗 ssh - Tmux window naming wrapper

ssh user@host  # Automatically renames tmux window to hostname
               # Restores window name after disconnect

🤖 update-ai - Update CLI AI tools

update-ai  # Updates Claude Code, Copilot CLI, and Codex CLI

🎯 sysup - Update OS packages

sysup  # Updates OS packages (apt/dnf/pacman), Flatpak, Homebrew, and AI tools

99-integrations.bash

Purpose: External tool integrations

🔍 FZF

# Loads from ~/.fzf.bash or system location
# Provides Ctrl+R history, Ctrl+T file finder

📝 Bash Completion

# macOS: Homebrew bash-completion
# Linux: /etc/bash_completion or /usr/share/bash-completion/

☸️ Kubectl Completion

source <(kubectl completion bash)
complete -o default -F __start_kubectl k  # Alias completion

⎈ Helm Completion

source <(helm completion bash)

🐳 Docker Completion

# Loads from /usr/share/bash-completion/completions/docker

🚀 Zoxide

eval "$(zoxide init bash)"  # Enables 'z' command

📜 Atuin

eval "$(atuin init bash)"  # Magical shell history

📂 Direnv

eval "$(direnv hook bash)"  # Auto-load .envrc files

🐳 OrbStack (macOS)

source ~/.orbstack/shell/init.bash

❄️ Nix

source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

🤬 TheFuck

eval "$(thefuck --alias)"  # Enables 'fuck' command

☁️ AWS Completion

complete -C aws_completer aws

🔀 Git Completion

# Loads from system or Homebrew location

🏗️ Terraform Completion

complete -C terraform terraform

🔗 Zsh ↔ Bash Comparison

Feature	Zsh	Bash
Framework	Oh-My-Zsh	None (manual)
Plugins	8 OMZ plugins	bash-completion
Autosuggestions	zsh-autosuggestions	N/A (use atuin)
Syntax highlighting	zsh-syntax-highlighting	N/A
Prompt	Starship	Starship ✅
PATH uniqueness	`typeset -U path`	Helper functions
Function removal	`unfunction`	`unset -f`
Completion	compinit	bash-completion

⚡ Performance

Startup Optimization

Lazy Loading - pyenv/jenv load on first use
Conditional Sources - Only load if tool exists
No Heavy Framework - Pure bash, no bloat

Benchmarking

# Time bash startup
time bash -i -c exit

# Detailed profiling
bash -x ~/.bashrc 2>&1 | head -50

🎯 Common Use Cases

Quick Navigation

z project        # Jump to frequently used directory
fcd              # Fuzzy find and cd to directory
..               # Go up one level

File Operations

ls               # List with icons (eza)
ll               # Long listing with git status
lt               # Tree view
cat file.txt     # Syntax highlighted (bat)
fv               # Fuzzy find and edit

Git Workflow

gst              # git status
ga               # git add -p (interactive)
gc "message"     # git commit -m
gp               # git push origin HEAD
glog             # Beautiful git log

Docker/Kubernetes

dco up           # docker compose up
k get pods       # kubectl get pods
kl pod-name      # kubectl logs -f

🔧 Customization

Adding Aliases

Edit ~/.bash/10-aliases.bash:

alias myalias='command'

Adding Functions

Edit ~/.bash/20-functions.bash:

myfunction() {
  # Your code
}

Adding Environment Variables

Edit ~/.bash/00-env.bash:

export MY_VAR="value"

Adding Tool Integrations

Edit ~/.bash/99-integrations.bash:

if command -v newtool >/dev/null 2>&1; then
  eval "$(newtool init bash)"
fi

🐛 Troubleshooting

Slow Startup?

# Profile startup
time bash -i -c exit

# Check what's loading
bash -x ~/.bashrc 2>&1 | head -100

Completion Not Working?

# Check bash-completion is loaded
type _init_completion

# Reinstall on macOS
brew reinstall bash-completion@2

Colors Not Working?

# Check LS_COLORS
echo $LS_COLORS

# Check vivid
vivid generate catppuccin-mocha

Tool Not Found?

# Check PATH
echo $PATH | tr ':' '\n'

# Check if tool exists
which toolname
command -v toolname

📦 Required Tools

# Core (install via Homebrew or apt)
brew install eza bat fd ripgrep vivid fzf zoxide atuin direnv neovim starship

# Optional
brew install xh thefuck

📚 Resources

Last updated: 2026-03-28 Maintained by: Jerome Soyer (@jsoyer)

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🐚 Bash Configuration

📁 Architecture

🎯 Why Bash?

🎨 Theme: Catppuccin Mocha / Snazzy

🚀 Modern CLI Tools

📝 File-by-File Documentation

~/.bash_profile

~/.bashrc

00-env.bash

🚀 _cache_eval() Helper

🌍 Platform Detection

🏠 Hostname Icons (Starship)

🌐 Locale

📜 History

🎨 Theme Configuration

01-path.bash

10-aliases.bash

🔧 Configuration

🚀 Modern Replacements

📂 Eza (ls replacement)

📁 Navigation

🔀 Git

🐳 Docker

☸️ Kubernetes

🔐 Security & Pentesting

🔐 SSH

20-functions.bash

📂 cx - Change directory and list

🔍 fcd - Fuzzy directory navigation

📋 f - Copy file path with FZF

✏️ fv - Open file in nvim with FZF

🔗 ssh - Tmux window naming wrapper

🤖 update-ai - Update CLI AI tools

🎯 sysup - Update OS packages

99-integrations.bash

🔍 FZF

📝 Bash Completion

☸️ Kubectl Completion

⎈ Helm Completion

🐳 Docker Completion

🚀 Zoxide

📜 Atuin

📂 Direnv

🐳 OrbStack (macOS)

❄️ Nix

🤬 TheFuck

☁️ AWS Completion

🔀 Git Completion

🏗️ Terraform Completion

🔗 Zsh ↔ Bash Comparison

⚡ Performance

Startup Optimization

Benchmarking

🎯 Common Use Cases

Quick Navigation

File Operations

Git Workflow

Docker/Kubernetes

🔧 Customization

Adding Aliases

Adding Functions

Adding Environment Variables

Adding Tool Integrations

🐛 Troubleshooting

Slow Startup?

Completion Not Working?

Colors Not Working?

Tool Not Found?

📦 Required Tools

📚 Resources

🚀 `_cache_eval()` Helper