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

77
README.md
View File

@@ -1,25 +1,30 @@
# profile
This project aims to create an advanced bash profile. It includes aliases,
a customized prompt and several functions for different purposes. It's mostly
targeted to system administrators but might satisfy some regular users.
## 1. Requirements
profile requires **Bash 4.3 or higher** (for associative arrays and namerefs).
It will refuse to load on older versions and will also refuse to load if the
current shell is not bash.
## 2. Getting started
Download and extract (or use git clone) the profile archive into your home
directory.
The profile is designed to be **sourced**, not executed directly.
Manual setup:
```bash
source <installpath>/profile/profile.sh
```
Automatic setup (recommended):
```bash
bash <installpath>/profile/profile.sh --install
```
@@ -34,6 +39,7 @@ bash <installpath>/profile/profile.sh --install --profile
You may also set the `PROFILE_PATH` environment variable before sourcing if you
want to override the automatic path detection:
```bash
export PROFILE_PATH=/opt/profile
source /opt/profile/profile.sh
@@ -48,6 +54,7 @@ files might interfere with some aliases and functions defined in profile.
In interactive shells (typical terminal sessions), profile enables
interactive-only features such as:
- aliases from `[aliases]`
- bash completion scripts from `profile.d/bash-completion/`
- prompt initialization (`PROMPT_COMMAND` and timer hook)
@@ -58,27 +65,32 @@ intentionally skipped to avoid side effects and startup noise. Public functions
remain available after sourcing, so scripts can still call profile helpers.
### 2.2. Initial configuration
Copy the example configuration file and customise it to your needs:
```bash
cp <installpath>/profile/doc/profile.conf.example <installpath>/profile/profile.conf
```
`profile.conf` is git-ignored so your personal settings will never be
accidentally committed. All keys are optional — sensible defaults apply when
unset. See [section 4](#4-configuration) for the full reference.
## 3. What's the purpose?
profile gives access to numerous functions, aliases and to an advanced prompt.
All functions are organized into modules under the `profile.d/` directory and
are loaded automatically at startup.
### 3.1. Prompt
A bar-style prompt showing current time, execution time of the last command
(with sub-millisecond precision), and the exit code of the last command.
### 3.2. Functions reference
| Function | Module | Description |
|---|---|---|
| --- | --- | --- |
| `busy` | fun | Monitor /dev/urandom for a hex pattern — look busy |
| `check_updates` | updates | Check whether a newer profile version is available online; when called with `-q` at startup a 3-second network timeout is applied so a slow or absent network never delays the prompt |
| `clean` | filefct | Erase backup files in given directories, optionally recursive |
@@ -129,6 +141,7 @@ A bar-style prompt showing current time, execution time of the last command
| `showinfo` | info | Display welcome banner and system information (figlet + neofetch/fastfetch) |
| `ssr` | ssh | SSH into a server as root, forwarding extra ssh options |
| `taz` | compress | Compress files and directories into a chosen archive format |
| `term_set` | conf | Set `TERM` to the best available terminal capability |
| `urlencode` | net | URL-encode a string |
| `utaz` | compress | Smartly uncompress archives (zip, tar.gz/bz2/xz/lz, rar, arj, lha, ace, 7z, zst, cpio, cab, deb, rpm) |
| `ver` | info | Display the installed profile version |
@@ -144,6 +157,7 @@ any custom completion definitions. profile already ships completions for its git
helper functions there (`git-completion.sh`).
## 4. Configuration
profile uses an INI-style configuration file (`profile.conf`) located in the
same directory as `profile.sh`. Sections are declared with `[section_name]` and
keys follow `key = value` syntax. Each module calls `load_conf "<section>"` at
@@ -158,11 +172,32 @@ template at `doc/profile.conf.example` (see [section 2.2](#22-initial-configurat
### 4.1. Core sections
| Section | Purpose |
|---|---|
| `[system]` | Bash history size, pager, and other shell behaviours |
| --- | --- |
| `[system]` | Bash history size, pager, terminal type, and other shell behaviours |
| `[general]` | General-purpose variables (e.g. compilation flags, `MAKEFLAGS`) |
| `[aliases]` | User command aliases, loaded for interactive shells only |
#### `TERM` — terminal type detection
The `TERM` key in `[system]` has special handling via `term_set`, which runs
automatically at startup:
| Value | Behaviour |
| --- | --- |
| *(absent or `smart`)* | Auto-detect the best available `terminfo` entry (default) |
| any other string | Exported as-is — standard Unix behaviour |
When auto-detection runs, emulator hints are checked in order, and the best
`terminfo` entry confirmed to exist on the system is selected:
1. **`$COLORTERM`** — `truecolor` or `24bit` → `xterm-direct`, then `xterm-256color`
2. **`$TERM_PROGRAM`** — `iTerm.app`, `WezTerm`, `Hyper`, `vscode` → appropriate entry
3. **`$VTE_VERSION`** — GNOME Terminal, Tilix, … → `vte-256color`, then `xterm-256color`
4. **`$WT_SESSION`** — Windows Terminal → `xterm-256color`
5. **`$TMUX`** — tmux session → `tmux-256color`, then `screen-256color`
6. **`$STY`** — GNU screen session → `screen-256color`, then `screen`
7. **Generic probe** — `xterm-256color` → `xterm-color` → `xterm` → `vt100`
### 4.2. Module defaults
Each module exposes its hardcoded defaults as configuration keys. Set a key to
@@ -171,7 +206,7 @@ change the default without having to pass flags every time.
**`[compress]`** — `taz` / `utaz`
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `TAZ_DEFAULT_FORMAT` | `tar.gz` | Archive format for `taz` (`tar.gz`, `tar.bz2`, `tar.xz`, `zip`, …) |
| `TAZ_DEFAULT_THREADS` | `auto` | Compression threads (`auto` = runtime CPU count, or explicit positive integer) |
| `TAZ_DEFAULT_LEVEL` | `6` | Compression level (1–9) |
@@ -181,7 +216,7 @@ change the default without having to pass flags every time.
**`[filefct]`** — file utilities
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `EXPANDLIST_DEFAULT_SEPARATOR` | ` ` (space) | Separator used by `expandlist` |
| `CLEAN_DEFAULT_RECURSIVE` | `0` | Set to `1` to make `clean` recurse into subdirectories |
| `RMSPC_DEFAULT_CHAR` | `_` | Replacement character used by `rmspc` |
@@ -190,7 +225,7 @@ change the default without having to pass flags every time.
**`[rain]`** — screensavers
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `RAIN_DEFAULT_SPEED` | `0.1` | Falling speed for `rain` |
| `RAIN_DEFAULT_COLOR` | `Green` | Colour for `rain` |
| `RAIN_DEFAULT_DENSITY` | dynamic | Maximum number of simultaneous falling elements for `rain` |
@@ -203,13 +238,13 @@ change the default without having to pass flags every time.
**`[ssh]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `SSH_DEFAULT_OPT` | _(empty)_ | Extra options passed to `ssr` (e.g. `-Y` for X forwarding) |
**`[pwd]`** — password tools
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `GENPWD_DEFAULT_LENGTH` | `16` | Generated password length |
| `GENPWD_DEFAULT_OCCURS` | `1` | Number of character class occurrences |
| `GENPWD_DEFAULT_COUNT` | `1` | Number of passwords to generate |
@@ -222,7 +257,7 @@ change the default without having to pass flags every time.
**`[fun]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `BUSY_DEFAULT_PATTERN` | `[0-9a-f]` | Hex pattern matched by `busy` |
| `BUSY_DEFAULT_DELAY` | `0.1` | Polling delay (seconds) for `busy` |
| `FAKE_COMPILE_DEFAULT_MIN_DELAY` | `40` | Min delay between output lines for `fake_compile` (ms) |
@@ -234,7 +269,7 @@ change the default without having to pass flags every time.
**`[git]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `GIT_MAIN_BRANCH` | `main` | Fallback main branch name used when remote HEAD cannot be detected |
| `GIT_DEFAULT_REMOTE` | `origin` | Default remote used by git helper functions |
| `GIT_WIP_PREFIX` | `wip` | Prefix used by `gwip` when generating automatic checkpoint messages |
@@ -243,13 +278,13 @@ change the default without having to pass flags every time.
**`[info]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `METEO_DEFAULT_CITY` | _(empty)_ | Default city for `meteo` when no argument is given |
**`[net]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `DWL_PREFERRED_TOOL` | _(empty)_ | Force `dwl` to use `curl`, `wget`, or `fetch` (auto-detected when unset) |
| `DWL_DEFAULT_RESUME` | `0` | Enable `dwl` resume mode by default (`1`/`true`/`yes`/`on`); applies to file downloads |
| `MYEXTIP_DEFAULT_URL` | `https://ip-api.com/json` | API endpoint used by `myextip` |
@@ -257,20 +292,20 @@ change the default without having to pass flags every time.
**`[packages]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `PKGS_DEFAULT_IGNORE_CASE` | `0` | Set to `1` to make `pkgs` case-insensitive by default |
**`[processes]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `PPU_DEFAULT_FORMAT` | `pid,user,comm,args` | `ps` output format used by `ppu` |
| `KU_DEFAULT_SIGNAL` | `TERM` | Default signal sent by `ku` |
**`[updates]`**
| Key | Default | Description |
|---|---|---|
| --- | --- | --- |
| `UPDT_DEFAULT_BRANCH` | `master` | Git branch used for update checks and `profile_upgrade`. Changing this value causes `profile_upgrade` to automatically switch the local checkout to the new branch on the next run and display a warning. |
### 4.3. Locale shortcuts
@@ -342,7 +377,7 @@ PROMPT_COLOR_DIR_FG = $IYellow
The twelve available `PROMPT_COLOR_*` keys are:
| Key | Role |
|---|---|
| --- | --- |
| `PROMPT_COLOR_TIME_FG` / `TIME_BG` | Clock foreground / background |
| `PROMPT_COLOR_BAR_BG` | Main bar background |
| `PROMPT_COLOR_OK_FG` / `OK_MARK` | Exit-code text / checkmark on success |
@@ -397,19 +432,23 @@ and other colour-aware tools.
True-colour themes (`solarized`, `solarized-light`) require a terminal with
24-bit colour support (Konsole, iTerm2, kitty, Alacritty, Windows Terminal).
Verify support with:
```bash
printf '\e[38;2;38;139;210mTrue colour test\e[0m\n'
```
## 5. Contact and more information
### 5.1. New users
If you use (or plan to use) `profile`, I'll be happy if you simply mail me to
let me know, especially if you don't plan to contribute. If you plan to
contribute, I'll be twice happier for sure!
### 5.2. Bugs
**profile** bug tracker is hosted on its Gitea instance. Check the
https://git.geoffray-levasseur.org/fatalerrors/profile page. If you find a bug,
<https://git.geoffray-levasseur.org/fatalerrors/profile> page. If you find a bug,
you can also submit a bug report to the maintainer mail address mentioned at
the end of that document. A bug report may contain the command line parameters
where the bug happens, OS details, the module that triggered it, if any, and the
@@ -422,6 +461,7 @@ Check the [FAQ](./doc/FAQ.md) and the [to-do list](./doc/todo.md) before
sending any feature request or bug report, as it might already be documented.
### 5.3. How to contribute?
You are free to improve and contribute as you wish. If you have no idea what to
do or want some direction, you can check the [to-do list](./doc/todo.md),
containing desired future improvements. Make sure you always have the latest
@@ -443,6 +483,7 @@ installation will probably be rejected.
If you want to make a financial contribution, please contact me by mail.
### 5.4. License, website, and maintainer
Everything except configuration files is licensed under the BSD-3 license.
Please check the license file alongside this one.
@@ -455,4 +496,4 @@ You can mail the author at fatalerrors \<at\> geoffray-levasseur \<dot\> org.
Documentation (c) 2021-2026 Geoffray Levasseur.
This file is distributed under the 3-clause BSD license. The complete license
agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause
agreement can be obtained at: <https://opensource.org/licenses/BSD-3-Clause>

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]**