# 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 bash /profile/profile.sh --install ``` This appends the required `source` line to both `~/.bashrc` and `~/.profile`. To target only one file: ```bash bash /profile/profile.sh --install --bashrc bash /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: ```bash source /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: ```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: ```bash #!/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`: ```bash 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: 1. The key is inside the correct `[section]` header. 2. There is no leading space before the section name (`[section]` not `[ section ]`). 3. The key is not commented out (no leading `#`). 4. 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`: ```ini [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: ```bash 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: ```bash # 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`: ```ini [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: ```ini [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: ```bash # 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: ```bash 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: ```bash help gacp help dwl help taz ``` This calls ` --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: ```bash 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?** ```bash 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](https://git.geoffray-levasseur.org/fatalerrors/profile/issues) or send a mail to `fatalerrors geoffray-levasseur org` with: - The exact command that triggered the bug - Your OS and Bash version (`bash --version`) - The module involved - Any relevant error output