diff --git a/README.md b/README.md index 9b3251b..d71e3d6 100644 --- a/README.md +++ b/README.md @@ -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 /profile/profile.sh ``` Automatic setup (recommended): + ```bash bash /profile/profile.sh --install ``` @@ -34,6 +39,7 @@ bash /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 /profile/doc/profile.conf.example /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 "
"` 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, + 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 \ geoffray-levasseur \ 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: diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 8336fed..ff5d111 100755 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -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 ` and delegates to ` --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 "` instead of `"Usage: kt "`. ### 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 - * Dagmar d'Surreal + +Forked default Bash profile from Beyond Linux From Scratch by: + +- James Robertson +- Dagmar d'Surreal diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index e254675..9070016 100755 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -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 geoffray-levasseur 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. diff --git a/doc/FAQ.md b/doc/FAQ.md index 96d6153..74f8084 100755 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -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 /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. --- @@ -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 /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 ` --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 geoffray-levasseur org` with: + - The exact command that triggered the bug - Your OS and Bash version (`bash --version`) - The module involved diff --git a/doc/todo.md b/doc/todo.md index f23e561..ea933a4 100755 --- a/doc/todo.md +++ b/doc/todo.md @@ -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]**