10 KiB
Executable File
Frequently Asked Questions
Installation & loading
Q: How do I install profile automatically into my shell startup files?
Run the installer directly (no need to source first):
bash <installpath>/profile/profile.sh --install
This appends the required source line to both ~/.bashrc and ~/.profile.
To target only one file:
bash <installpath>/profile/profile.sh --install --bashrc
bash <installpath>/profile/profile.sh --install --profile
The operation is idempotent — running it again will not add a duplicate line.
Q: I ran profile.sh directly and got a warning about sourcing.
profile.sh is designed to be sourced, not executed:
source <installpath>/profile/profile.sh
The only exception is --install, which must be passed to a direct execution
(bash profile.sh --install) to set up the sourcing line automatically.
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: Can I use profile functions in scripts?
Yes. The supported way is to source profile.sh from a Bash script:
#!/usr/bin/env bash
source /path/to/profile/profile.sh
taz -p auto -f lz mydir
You can also source one module directly (for example
profile.d/compress.sh) if you only need a subset of functions.
When you source a module directly, profile configuration parsing/loading from
profile.sh is skipped, so defaults from profile.conf are not applied unless
your script loads them explicitly.
profile.sh also detects whether the current shell is interactive. In
non-interactive shells (typical script execution), interactive-only features
are intentionally disabled: prompt setup, aliases, welcome/info messages, and
startup update checks are not enabled.
In all cases, avoid aliases in scripts. Use real commands/functions instead, because alias expansion is interactive-shell oriented and can be disabled or behave differently in non-interactive execution.
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, but you can create your
own theme.
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).
Git helpers
Q: What git helper functions does profile provide?
All git helpers are defined in profile.d/git.sh (new in 4.1.0):
| Command | Purpose |
|---|---|
gst |
Compact status with branch tracking info |
ggraph |
Decorated history graph |
gsync |
Fetch and rebase onto upstream |
gacp |
Add, commit and push in one command |
greset |
Reset to upstream, stashing local changes first |
gwip |
Quick WIP checkpoint commit |
gprune |
Delete merged local branches |
groot |
Print or cd to repository root |
All commands accept -h / --help.
Q: Tab completion for gacp does not show modified files.
Profile ships dedicated completions in profile.d/bash-completion/git-completion.sh,
loaded automatically in interactive sessions. If completions are missing,
check that the system git completion is installed:
# Debian / Ubuntu
apt-get install bash-completion
# Fedora / RHEL
dnf install bash-completion
When the native git completion helpers are available, gacp path completion
behaves exactly like git add (modified files, untracked files, directories).
Q: gacp says "No files specified" even though I passed -a.
The -a / --auto flag adds all modified files (equivalent to git add -A).
The default depends on GIT_GACP_AUTO_ADD in profile.conf:
[git]
GIT_GACP_AUTO_ADD = 1
Set to 1 to make -a the default.
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: How do I limit how long dwl waits for a download?
Use the -t / --timeout option:
dwl -t 5 https://example.com/file.txt /tmp/file.txt
This sets a 5-second cap on both the connection and the overall transfer.
The timeout is propagated to curl (--max-time + --connect-timeout),
wget (--timeout), or fetch (-T) transparently.
Q: The prompt takes a long time to appear when my network is unavailable.
Fixed in 4.1.0. check_updates -q (called at startup) now enforces a
3-second network timeout. If the update server is unreachable the check
fails silently and the prompt appears immediately.
Q: help only shows a list of functions. Can I get usage for a specific one?
Yes — pass the command name as an argument:
help gacp
help dwl
help taz
This calls <command> --help and prints the full usage for that function.
Q: pkgs does not find packages I know are installed.
pkgs uses get_pkgmgr to detect the active package manager and delegates
to the appropriate tool. Supported families: apt (Debian/Ubuntu),
dnf / yum (RHEL/Fedora), zypper (openSUSE), pacman (Arch),
apk (Alpine), portage (Gentoo), xbps (Void), nix, brew (macOS).
If your distribution is not detected, run get_pkgmgr to see what is
identified, and check that the package manager binary is in your PATH.
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