fatalerrors/profile
1
0
Fork 0
Code Issues Pull Requests Projects Releases 10 Wiki Activity

updated and fixed doc (markdown spellcheck)

Browse Source
This commit is contained in:
fatalerrors
2026-05-28 18:08:41 +02:00
parent 481cc94fa8
commit 3e0bedd9c8
5 changed files with 219 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
doc/FAQ.md
View File

@@ -7,15 +7,19 @@
**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.
---
@@ -23,9 +27,11 @@ 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.
@@ -35,11 +41,13 @@ The only exception is `--install`, which must be passed to a direct execution
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.
---
@@ -55,12 +63,14 @@ 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.
@@ -82,10 +92,12 @@ 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.
@@ -119,6 +131,7 @@ 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 ]`).
@@ -128,15 +141,39 @@ Check that:
---
**Q: How do I force or auto-detect the correct `TERM` value?**
Set `TERM` in the `[system]` section of `profile.conf`:
```ini
[system]
# Auto-detect best available terminfo entry at startup (default)
#TERM=smart
# Force a specific entry
#TERM=xterm-256color
```
When `TERM` is absent or set to `smart`, `term_set` probes your terminal
emulator's environment variables (`COLORTERM`, `TERM_PROGRAM`, `VTE_VERSION`,
`WT_SESSION`, `TMUX`, `STY`) and then tests terminfo entries in preference
order. If you are experiencing display issues, run `term_set` interactively
and check the result with `echo $TERM`. See *Prompt & theming* below for
symptoms caused by a wrong `TERM` value.
---
## 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.
@@ -147,16 +184,45 @@ own theme.
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.**
**Q: My prompt colours are missing, wrong, or ANSI escape codes appear as raw text.**
The most common cause is a `TERM` value that does not match what your terminal
emulator actually supports — either it points to an entry that does not exist
in the local `terminfo` database, or it under-describes the real capabilities
(e.g. `TERM=xterm` when the emulator supports 256 colours).
Diagnose with:
```bash
echo "TERM=$TERM"
tput colors # should print 256 (or higher) for a capable terminal
infocmp | head -5 # verify the loaded terminfo entry looks sane
```
Common scenarios and fixes:
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `tput: unknown terminal` | `TERM` value has no terminfo entry | Remove the forced value and let `TERM=smart` auto-detect |
| Only 8 colours instead of 256 | `TERM=xterm` instead of `xterm-256color` | Set `TERM=smart` or force `xterm-256color` |
| Colours correct in plain shell but wrong inside tmux | tmux overwrites `TERM` | Set `TERM=smart` — `term_set` picks `tmux-256color` |
| Colours correct outside screen but wrong inside it | Same, for GNU screen | Set `TERM=smart` — `term_set` picks `screen-256color` |
| Prompt renders correctly but `rain` / `matrix` shows garbage | Terminal doesn't support the ANSI codes implied by `TERM` | Match `TERM` to the real emulator capability |
The recommended approach is to leave `TERM` unset (or set it to `smart`) in
`profile.conf` and let `term_set` choose the best available entry automatically.
Only force a specific value if auto-detection picks the wrong one.
Theme files are parsed, not executed. Only `PROMPT_COLOR_*` keys and the
standard colour variable names from `disp.sh` (`Black`, `Blue`, `On_IBlack`,
@@ -181,7 +247,7 @@ theme file cannot execute code. Values must be a colour variable reference
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 |
@@ -200,12 +266,14 @@ All commands accept `-h` / `--help`.
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).
@@ -215,10 +283,12 @@ behaves exactly like `git add` (modified files, untracked files, directories).
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.
---
@@ -229,6 +299,7 @@ Set to `1` to make `-a` the default.
The key is `METEO_DEFAULT_CITY` (not `DEFAULT_CITY`), and it must be in the
`[info]` section:
```ini
[info]
METEO_DEFAULT_CITY = Paris
@@ -240,6 +311,7 @@ METEO_DEFAULT_CITY = Paris
`dwl` requires one of `curl`, `wget`, or `fetch` to be installed.
Install curl:
```bash
# Debian / Ubuntu
apt-get install curl
@@ -247,6 +319,7 @@ apt-get install curl
# Fedora / RHEL
dnf install curl
```
Or set `DWL_PREFERRED_TOOL` in `[net]` to whichever tool you have.
---
@@ -254,9 +327,11 @@ 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.
@@ -274,11 +349,13 @@ 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.
---
@@ -299,9 +376,11 @@ identified, and check that the package manager binary is in your `PATH`.
`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.
---
@@ -332,6 +411,7 @@ has not been implemented yet.
```bash
PROFILE_DISABLED=1 bash --norc
```
Or simply open a shell without sourcing `~/.bashrc` (`bash --norc`).
---
@@ -341,6 +421,7 @@ Or simply open a shell without sourcing `~/.bashrc` (`bash --norc`).
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