6.0 KiB
Executable File
Frequently Asked Questions
Installation & loading
Q: profile refuses to load and prints "This profile requires Bash 4.3 or higher."
Your system's default shell is an older Bash (common on macOS, which ships Bash 3.x for licensing reasons). Install a newer Bash:
# macOS
brew install bash
# then add /opt/homebrew/bin/bash to /etc/shells and chsh
Or point your terminal emulator at the newer binary explicitly.
Q: I sourced profile.sh but functions are not available in sub-shells or scripts.
All public functions are exported with export -f. They are available in
child Bash processes, but not in POSIX sh sub-shells. Make sure your
scripts start with #!/usr/bin/env bash.
Q: I set PROFILE_PATH but profile still can't find its modules.
PROFILE_PATH must be exported before you source profile.sh:
export PROFILE_PATH=/opt/profile
source /opt/profile/profile.sh
If set after sourcing, MYPATH is already locked in and the variable has
no effect.
Q: Can I load profile system-wide via /etc/profile?
It is not recommended. User .bashrc files frequently set variables that
conflict with the aliases and locale functions defined here, leading to
surprising behaviour. Per-user sourcing from ~/.bashrc is the supported
method.
Configuration
Q: I edited profile.conf but my changes have no effect.
profile.conf is parsed once per shell session at load time. Open a new
terminal (or exec bash) to pick up the changes. There is no live-reload.
Q: How do I find out which configuration keys a module supports?
Every supported key is documented with a comment in profile.conf.
See also README.md §4.2 for a consolidated table.
Q: A key I set in profile.conf is being ignored.
Check that:
- The key is inside the correct
[section]header. - There is no leading space before the section name (
[section]not[ section ]). - The key is not commented out (no leading
#). - The value contains no backticks or
$(…)— these are stripped by the parser as a security measure.
Prompt & theming
Q: How do I change the prompt theme?
Add to profile.conf:
[prompt]
PROMPT_THEME = dark
Built-in names: default, dark, light, solarized, solarized-light,
monokai, monochrome, abyss, plasma, adwaita.
Q: The solarized or solarized-light theme shows wrong colours.
Those themes use 24-bit / true-colour ANSI sequences (\e[38;2;R;G;Bm).
Test your terminal:
printf '\e[38;2;38;139;210mTrue colour test\e[0m\n'
If you see a solid blue word your terminal supports true colour.
If you see garbage or plain text, switch to a 16-colour theme
(dark, default, etc.) or upgrade your terminal emulator.
Q: I created a custom theme but load_theme emits "key not allowed" warnings.
Theme files are parsed, not executed. Only PROMPT_COLOR_* keys and the
standard colour variable names from disp.sh (Black, Blue, On_IBlack,
…) are accepted. Any other key — including custom variables — is rejected.
See README.md §4.4 for the full list of accepted keys and value forms.
Q: Can a theme file contain shell logic or $(…) command substitutions?
No, and intentionally so. Theme files are parsed line-by-line; shell
constructs are never evaluated. This is a security boundary — a malicious
theme file cannot execute code. Values must be a colour variable reference
($Blue) or a raw ANSI escape literal (\e[0;34m).
Functions
Q: meteo prints "No city specified" even though I set a default.
The key is METEO_DEFAULT_CITY (not DEFAULT_CITY), and it must be in the
[info] section:
[info]
METEO_DEFAULT_CITY = Paris
Q: dwl fails with "no download tool found".
dwl requires one of curl, wget, or fetch to be installed.
Install curl:
# Debian / Ubuntu
apt-get install curl
# Fedora / RHEL
dnf install curl
Or set DWL_PREFERRED_TOOL in [net] to whichever tool you have.
Q: pkgs does not find packages I know are installed.
pkgs delegates to dpkg -l (Debian/Ubuntu) or rpm -qa (RHEL/Fedora).
If your distribution uses a different package manager (pacman, apk, brew …)
it is not yet supported. See doc/todo.md for the tracking issue.
Q: profile_upgrade says "no update available" but I know there is one.
check_updates compares the content of the remote version file against
$PROFVERSION. If UPDT_DEFAULT_BRANCH in [updates] points to a different
branch than your installation, the version files may not match. Check:
cat "$MYPATH/version"
and make sure UPDT_DEFAULT_BRANCH matches the branch you track.
Compatibility
Q: Some functions misbehave on macOS / Cygwin.
Both environments ship non-GNU userland utilities with different flags and behaviour. profile is primarily developed and tested on Linux (Debian and RHEL families). macOS and Cygwin bugs are low priority; patches that add compatibility without breaking Linux support are welcome.
Q: Can I use profile with ZSH?
Not officially. Blockers include local -A (ZSH requires typeset -A) and
local -n namerefs. A compatibility layer is listed in doc/todo.md but
has not been implemented yet.
Miscellaneous
Q: How do I completely disable profile for one session?
PROFILE_DISABLED=1 bash --norc
Or simply open a shell without sourcing ~/.bashrc (bash --norc).
Q: How do I report a bug?
Open an issue on the
Gitea tracker
or send a mail to fatalerrors <at> geoffray-levasseur <dot> org with:
- The exact command that triggered the bug
- Your OS and Bash version (
bash --version) - The module involved
- Any relevant error output