321 lines
9.1 KiB
Markdown
Executable File
321 lines
9.1 KiB
Markdown
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
|
|
bash <installpath>/profile/profile.sh --install
|
|
```
|
|
This appends the required `source` line to both `~/.bashrc` and `~/.profile`.
|
|
To target only one file:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```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`:
|
|
```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 `<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:
|
|
```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 <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
|