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

62
doc/CHANGELOG.md
View File

@@ -10,6 +10,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## [4.1.0] — 2026-05-07
### Added
- `profile.sh --install` command to automatically configure profile loading in
shell startup files.
- `--install --bashrc` and `--install --profile` target selectors for
@@ -20,16 +21,17 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
automatically in interactive sessions from `profile.d/bash-completion/*.sh`.
### Changed
- `disp` now wraps long messages on terminal width, avoids mid-word splits, and
aligns continuation lines with the message body after the prefix.
- `help` now supports `help <command>` and delegates to `<command> --help`.
- `taz` now supports `-p auto` / `--parallel=auto` to automatically use the
runtime CPU count. This mode is now the default via
`TAZ_DEFAULT_THREADS=auto`.
- `taz` keeps backward compatibility with legacy `TAZ_DEFAULT_THREADS=0`
values by interpreting `0` as `auto`.
`TAZ_DEFAULT_THREADS=auto`. Backward compatibility with 0 being interpreted as
auto is maintained.
### Fixed
- Startup responsiveness improved: `check_updates -q` now uses a short network
timeout so unavailable/slow networks no longer delay prompt readiness.
- `dwl` gained timeout support (`-t` / `--timeout`) and is now used by quiet
@@ -40,6 +42,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## [4.0.0] — 2026-04-23
### Added
- New `profile.conf` reference template at `doc/profile.conf.example`.
- Dynamic locale shortcuts generated from `SET_LOCALE` and startup default
language selection through `DEFAULT_LANG`.
@@ -49,11 +52,13 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
- Module defaults exposed as configuration keys in `profile.conf`.
### Changed
- `utaz` now supports a wider range of archive formats.
- Prompt and theme rendering improved, including better 24-bit color support.
- Overall code quality and maintainability improved across modules.
### Documentation
- README updated with full function reference and configuration tables.
- New and expanded docs in `doc/` (`CONTRIBUTING.md`, `FAQ.md`, `todo.md`).
- Historical releases imported from `history.txt` into this changelog.
@@ -63,6 +68,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## [3.99.2-4_rc_2] — 2026-04-21
### Fixed
- **`prompt.sh`** — `\$Last_Command` in PS1 was escaped, preventing the exit
code from ever appearing in the prompt (the local variable no longer exists
when PS1 is rendered by bash). Removed the backslash so the value is embedded
@@ -77,6 +83,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
`"Usage: ppg <string>"` instead of `"Usage: kt <pid>"`.
### Added
- **`packages.sh` — `get_pkgmgr()`** — new exported helper that detects the
active package manager of the running distribution. Detection first reads
`/etc/os-release` (`ID` then `ID_LIKE`), then falls back to a
@@ -89,6 +96,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## [3.99.1-4_rc_1] — 2026
### Added
- **Theming system** — `load_theme` in `profile.d/prompt.sh` loads `.theme`
files from `profile.d/themes/` (or a custom directory set via
`PROMPT_THEME_DIR`). Theme files are **parsed, not executed** — no shell code
@@ -116,6 +124,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
never accidentally staged.
### Changed
- README §2 now explains how to create `profile.conf` from
`doc/profile.conf.example` (new section 2.1 "Initial configuration").
- README §4 updated with full module-defaults tables, theming reference, and a
@@ -124,6 +133,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
variables, only data).
### Security
- `load_theme` uses a strict allowlist (no `eval`, no sourcing). Only
`PROMPT_COLOR_*` keys and known `disp.sh` colour variable names are accepted.
Values must match `\$[A-Za-z_][A-Za-z0-9_]*` or `\\e\[[0-9;]*m`; any other
@@ -134,6 +144,7 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## [3.95.3-4_beta_3] — 2024
### Added
- Initial public release candidate series.
- Core modules: `compress`, `disp`, `filefct`, `fun`, `help`, `info`, `lang`,
`net`, `packages`, `processes`, `prompt`, `pwd`, `rain`, `ssh`, `updates`.
@@ -151,35 +162,43 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
## Legacy releases (imported from `history.txt`)
### [3.6.1] — 2026-03-05
- Fix typo in `compress.sh`.
### [3.6.0] — 2026-03-05
- Improved `utaz` with broader multi-format support.
- Introduced `ppu` and `ppn`.
- Improved update system.
### [3.5.0] — 2026-03-04
- `rain` now has configurable speed and color.
- `showinfo` adapted to `fastfetch` (in addition to `neofetch`).
### [3.3.1] — 2022-02-24
- Fixed version detection.
- Added `busy`.
- Fixed use of library functions before loading.
### [3.3.0] — 2022-11-28
- Initial version update support.
- Changed versioning code.
- Added installation path detection.
### [3.2.3] — 2022-11-28
- Improved README.
### [3.2.2] — 2022-11-21
- Fixed `taz` compression level parsing.
- Fixed typo in `dpkgs`.
### [3.2.1] — 2022-11-20
- Fixed several messages.
- Made `dpkgs` RPM-aware (initial support).
- Removed version history from main script and reverted declaration order.
@@ -187,108 +206,139 @@ Versions follow `MAJOR.MINOR.PATCH-REVISION_STAGE_N` (e.g. `3.99.1-4_rc_1`).
- Completed `LICENSE` file.
### [3.2.0] — 2022-11-18
- Created `disp` command and integrated it across the codebase.
### [3.1.1] — 2022-11-10
- `genpwd`: added feasibility check for requested password constraints.
### [3.1.0] — 2022-11-08
- Added password generator.
### [3.0.1] — 2022-11-07
- Added concatenation option to `rmspc`.
- Added `ku`.
- Improved error handling in `meteo`.
### [3.0.0] — 2022-08-27
- Split code into several files/modules.
- Added `rain` screensaver.
### [2.8.2] — 2022-07-29
- Added warning for non-bash users.
### [2.8.1] — 2022-07-19
- Cleanup, fixes and optimizations.
### [2.8.0] — 2022-06-24
- Added `backtrace`, `error` and `settrace`.
- Bugfixes in `showinfo`.
### [2.7.1] — 2022-06-22
- Minor corrections.
- Added `help` command.
### [2.7.0] — 2022-06-21
- Added `isipv4` and `isipv6`, integrated into `rmhost`.
- Removed broken Konsole save/restore support.
### [2.6.3] — 2021-10-18
- Changed PS1 to status-bar style.
- Minor improvements.
### [2.6.2] — 2021-02-26
- Bugfix in `taz` for directories with trailing slash.
### [2.6.1] — 2020-12-25
- Added checks in `rmhost`.
- Improved `rmspc`.
- Created `expandlist`.
### [2.6.0] — 2020-10-24
- Added Konsole session save/restore.
### [2.5.3] — 2020-09-11
- Added aliases, improved code consistency and fixed typos.
- Improved `utaz`, removed `showdiskmap`, removed remaining French text.
- Added license information for future publication.
### [2.5.2] — 2020-03-06
- Sorted and improved aliases.
### [2.5.1] — 2020-03-05
- Language consistency fixes.
- Added `pigz` support in `taz`.
### [2.5.0] — 2020-03-03
- Added `taz` and `rmspc`.
- Renamed `auzip` to `utaz` and improved it.
### [2.4.0] — 2020-03-02
- Added `auzip`.
### [2.3.2] — 2020-01-31
- `figlet`: changed default font to `ansi_shadow`.
### [2.3.1] — 2020-01-16
- Bugfix: non-interactive shells were blocked by some functions.
### [2.3.0] — 2020-01-08
- Added `figlet` and `neofetch` as MOTD replacement.
### [2.2.0] — 2019-12-16
- Added `showinfo`.
- First implementation of `showdiskmap`.
### [2.1.2] — 2019-09-24
- Bugfix in profile version display.
### [2.1.1] — 2019-09-23
- Bugfix in `dpkgs`.
### [2.1.0] — 2018-09-16
- Added `rmhost`, `setc`, `setfr`.
- Improved locale management.
### [2.0.1] — 2017-02-04
- `clean` improvements (`--shell`).
### [2.0.0] — 2015-10-24
- Added advanced functions (`clean`, `ssr`, etc.).
### [1.0.0] — 2013-02-16
- Initial version.
### [Initial fork]
Forked default Bash profile from Beyond Linux From Scratch by
* James Robertson <jameswrobertson@earthlink.net>
* Dagmar d'Surreal <rivyqntzne@pbzpnfg.arg>
Forked default Bash profile from Beyond Linux From Scratch by:
- James Robertson <jameswrobertson@earthlink.net>
- Dagmar d'Surreal <rivyqntzne@pbzpnfg.arg>

15
doc/CONTRIBUTING.md
View File

@@ -39,6 +39,7 @@ to target). Stale forks cause avoidable merge conflicts.
**New functionality** must always target `master`.
**Bugfixes** must target the branch where the bug was introduced:
- If the bug exists in a released version, open the fix against that version's
maintenance branch first, then cherry-pick onto `master`.
- If the bug is only in `master` (unreleased), fix it directly on `master`.
@@ -71,13 +72,15 @@ Any experimental version must have it's dedicated branch.
---
## 5. Development environment
|---|---|---|
| --- | --- | --- |
| Bash | 4.3 | Namerefs (`local -n`) required |
| shellcheck | any recent | Run before every commit |
| git | any | For contributing patches |
| bats-core | 1.x | Optional — for running the test suite |
Install shellcheck:
```bash
# Debian / Ubuntu
apt-get install shellcheck
@@ -94,6 +97,7 @@ brew install shellcheck
## 6. Code style
### General rules
- **Bash only** — no external interpreters in core modules. Python or Perl is
acceptable for completely self-contained, optional utilities that have no
dependencies beyond a minimal Debian or CentOS installation.
@@ -109,6 +113,7 @@ brew install shellcheck
`${VAR:-default}` and document the key in `profile.conf` and `README.md §4`.
### Function conventions
- Public functions **must** be exported: `export -f funcname`.
- Every public function **must** support `-h` / `--help` and print usage to
stdout, returning 0.
@@ -120,6 +125,7 @@ brew install shellcheck
to prevent collisions with caller-scope variables.
### Module structure
Every new module should follow this pattern:
```bash
@@ -172,20 +178,25 @@ comment explaining why the suppression is necessary.
## 10. Submitting a contribution
### Via Git (preferred)
1. Contact the maintainer to obtain push access, or fork on the Gitea instance.
2. Create a branch: `git checkout -b feature/my-feature`.
3. Commit with a clear subject line: `module: short description (≤ 72 chars)`.
4. Push and open a pull request against `master`.
### Via patch
If you do not have push access:
```bash
git format-patch origin/master
```
Send the resulting `.patch` file(s) to
`fatalerrors <at> geoffray-levasseur <dot> org`.
### Commit message format
```
module: imperative short description
@@ -197,7 +208,7 @@ Reference issue numbers if applicable: closes #42.
## 11. What will be rejected
- Code requiring packages not in a minimal Debian or CentOS install.
- Code requiring packages not in a minimal Debian or CentOS install, unless optionnal.
- Use of `eval`, `source`-based config loading, or other code-injection vectors.
- Changes that break Bash 4.3 compatibility.
- Patches without a passing `shellcheck` run.

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

8
doc/todo.md
View File

@@ -47,23 +47,27 @@ version-bump.
## Module improvements
### compress
- [ ] **`taz` progress bar** — show a `pv` / `dd`-based progress indicator when
compressing large trees, gated behind a `-p` flag. **[medium]**
- [ ] **`utaz` integrity check** — run `tar -tOf` / `unzip -t` / `7z t` before
extracting and abort if the archive is corrupt. **[easy]**
### filefct
- [ ] **`findbig` / `findzero` / `finddead` — `fd` integration** — optionally
use `fd` instead of `find` when available for faster traversal. **[easy]**
- [ ] **`file_stats` — human-readable totals** — add `--human` flag to emit
sizes in K/M/G instead of bytes. **[easy]**
### info
- [X] **`showinfo` fallback** — when neither `neofetch` nor `fastfetch` is
installed, print a minimal sysinfo block (hostname, OS, kernel, uptime,
CPU, RAM) using pure Bash + `/proc`. **[medium]**
### net
- [X] **`dwl` resume support** — pass `-C -` to curl / `--continue-at -` to
wget for interrupted downloads; gate behind a `-r` flag. **[easy]**
- [ ] **`myextip` multiple providers** — fall back to a secondary URL
@@ -71,15 +75,18 @@ version-bump.
**[easy]**
### processes
- [X] **`ku` dry-run flag** — add `-n` / `--dry-run` to print what would be
killed without acting. **[easy]**
### pwd
- [ ] **`genpwd` passphrase mode** — add `-w` / `--words N` to generate
word-based passphrases (diceware-style) from `/usr/share/dict/words`.
**[medium]**
### ssh
- [ ] **SSH agent management** — add `ssh_agent_start` / `ssh_agent_stop` helpers
that start a persistent `ssh-agent`, add configured keys, and survive
re-login via a socket stored in `~/.ssh/agent.env`. **[medium]**
@@ -87,6 +94,7 @@ version-bump.
matching entries in one call. **[easy]**
### updates
- [ ] **Automatic update check age** — store a timestamp in `~/.cache/profile_last_check`;
skip the network request in `check_updates -q` if the last check was less
than `UPDT_CHECK_INTERVAL` hours ago (configurable, default 24). **[medium]**