bash/README.md

Bash configuration

This repository owns configuration that is specific to interactive Bash and the Bash login sequence.

Responsibilities

• Install ~/.bash_profile and ~/.bashrc as symlinks into this repository.
• Make login Bash load the shared ~/.profile environment before .bashrc.
• Configure Bash history, prompt rendering, completion and command-not-found behaviour.
• Initialize Bash integrations such as NVM, Pyenv, z.lua and gitstatus.
• Own interactive aliases, functions and their curated command catalogue.
• Isolate Arch-specific interactive commands from general Bash configuration.
• Display the startup greeting and cached package status.
• Display TODO.md and .autonote.md after successful directory changes.

Boundaries

This repository does not own:

• Portable login environment variables or shared PATH construction. Those belong in the profile repository.
• User services, timers or background refresh logic. Those belong in the systemd repository. Bash may consume their cached output or request a non-blocking service start.
• Secrets, machine credentials or project-specific environment settings.

Startup flow

A login Bash reads:

~/.bash_profile -> ~/.profile -> ~/.bashrc

A non-login interactive Bash reads only ~/.bashrc and inherits the login environment from its parent process. .bashrc returns immediately when the shell is not interactive.

Files

• bash_profile: connects Bash login startup to the shared profile and Bash RC.
• bashrc: interactive guard and ordered module loader.
• bashrc.d/: numbered interactive Bash modules; lower numbers load first.
• interactive.sh: loads interactive aliases, functions and reminders.
• aliases.sh: general interactive aliases and functions, written portably.
• aliases.bash: aliases requiring Bash-specific naming or behaviour.
• commands.sh: command-catalogue display and validation functions.
• commands.tsv: curated command descriptions and reminder visibility.
• commands.README.md: format and maintenance instructions for the catalogue.
• hosts.sh: SSH destination listing function.
• memory.tsv: curated daily shell-memory questions and answers.
• memory.README.md: memory-bank format and selection behaviour.
• platform/arch.sh: Arch-specific applications and system integration.
• gitstatus-custom.sh: prompt integration for gitstatus.
• cheat.bash: completion for cheat.
• install.sh: installs the home-directory symlinks and gitstatus dependency.

Run install.sh when initially installing the repository. It preserves an existing destination before creating each symlink.

Bash RC modules

The loader sources every readable bashrc.d/*.bash file in lexical order:

• 00-core.bash: colors, history, terminal and Readline settings.
• 10-prompt.bash: prompt, gitstatus and per-command history flushing.
• 20-greeting.bash: calendar-day greeting and adjective selection.
• 30-integrations.bash: interactive commands, NVM and z.lua.
• 40-status.bash: command reminders, memory and cached package status.
• 50-completions.bash: command-specific completion setup.
• 60-directory-notes.bash: TODO.md and .autonote.md display after cd.
• 70-development.bash: OpenCode and Pyenv initialization.
• 90-memory-question.bash: persisted shuffled question deck, answerpls and on-demand refreshpls rotation.

Keep cross-module dependencies explicit through this numbering. New modules should own one coherent area rather than becoming another general-purpose RC.

Package-status integration

40-status.bash is a read-only consumer of the package cache at ~/.cache/package-status/status. It never runs Pacman or synchronizes package databases during shell startup. When the cache is missing, stale or predates a local package transaction, Bash requests a non-blocking start of package-status-refresh.service, subject to a five-minute retry backoff.

The refresh service and 30-minute timer are owned and documented by the systemd repository. The Arch update wrapper in this repository also requests a refresh after a successful upgrade.