profile/README.md

# 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. You will have to modify your `~/.bashrc` and/or `~/.profile` file to
add at the end (preferably):
```bash
source <installpath>/profile/profile.sh
```

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
```

It's not recommended to load that profile in `/etc/profile` as users' `.bashrc`
files might interfere with some aliases and functions defined in profile.

### 2.1. 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 |
| `clean` | filefct | Erase backup files in given directories, optionally recursive |
| `disp` | disp | Display formatted info / warning / error / debug messages |
| `dwl` | net | Download a URL using curl, wget, or fetch transparently |
| `expandlist` | filefct | Expand glob expressions into a quoted, separated list |
| `file_stats` | filefct | Display file size statistics for a path |
| `findbig` | filefct | Find the biggest files in the given or current directory |
| `finddead` | filefct | Find dead symbolic links in the given or current directory |
| `findzero` | filefct | Find empty files in the given or current directory |
| `genpwd` | pwd | Generate one or more random secure passwords with configurable constraints |
| `gpid` | processes | Give the list of PIDs matching the given process name(s) |
| `help` | help | Display the list of available functions and basic usage |
| `isipv4` | net | Tell if the given parameter is a valid IPv4 address |
| `isipv6` | net | Tell if the given parameter is a valid IPv6 address |
| `ku` | processes | Kill all processes owned by the given user name or ID |
| `matrix` | rain | Console screensaver with Matrix-style digital rain (binary, kana, ascii charset) |
| `mcd` | filefct | Create a directory and immediately move into it |
| `meteo` | info | Display weather forecast for the configured or given city |
| `myextip` | net | Get information about your public IP address |
| `get_pkgmgr` | packages | Detect the active package manager of the running distribution (`apt`, `dnf`, `yum`, `zypper`, `pacman`, `apk`, `portage`, `xbps`, `nix`) |
| `pkgs` | packages | Search for a pattern in installed package names (distro-aware via `get_pkgmgr`, supports `-i`) |
| `ppg` | processes | Look for the given pattern in running processes |
| `ppn` | processes | List processes matching an exact command name |
| `ppu` | processes | List processes owned by a specific user |
| `profile_upgrade` | updates | Upgrade profile to the latest version (git pull or archive) |
| `pwdscore` | pwd | Calculate the strength score of a given password |
| `rain` | rain | Console screensaver with falling-rain effect (multiple color themes) |
| `rmhost` | ssh | Remove host (name and IP) from SSH known_hosts; supports `--all-users` as root |
| `rmspc` | filefct | Replace spaces in filenames with underscores (or a custom character) |
| `setc` | lang | Set locale to standard C (POSIX) |
| `setlocale` | lang | Set console locale to any installed locale |
| `settrace` | debug | Activate or deactivate ERR trap to display backtrace on script errors |
| `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 |
| `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 |

Locale shortcut functions (`setfr`, `setus`, etc.) are dynamically generated at
startup from the `SET_LOCALE` configuration key (see section 4).

## 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
load time, which exports every key in that section as an environment variable.
Unknown keys are silently ignored; all keys are optional — sensible defaults
apply when unset.

`profile.conf` is listed in `.gitignore` so personal values (API keys, cities,
compiler flags, …) are never accidentally staged. Start from the annotated
template at `doc/profile.conf.example` (see [section 2.1](#21-initial-configuration)).

### 4.1. Core sections

| Section | Purpose |
|---|---|
| `[system]` | Bash history size, pager, and other shell behaviours |
| `[general]` | General-purpose variables (e.g. compilation flags, `MAKEFLAGS`) |
| `[aliases]` | User command aliases, loaded for interactive shells only |

### 4.2. Module defaults

Each module exposes its hardcoded defaults as configuration keys. Set a key to
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` | `0` | Compression threads (0 = auto-detect) |
| `TAZ_DEFAULT_LEVEL` | `6` | Compression level (1–9) |
| `UTAZ_DEFAULT_DELETE` | `0` | Set to `1` to delete the source archive after extraction |
| `UTAZ_DEFAULT_DIR_MODE` | `0` | Set to `1` to always extract into a subdirectory |

**`[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` |
| `FINDBIG_DEFAULT_LIMIT` | `10` | Number of results returned by `findbig` |

**`[rain]`** — screensavers

| Key | Default | Description |
|---|---|---|
| `RAIN_DEFAULT_SPEED` | `0.1` | Falling speed for `rain` |
| `RAIN_DEFAULT_COLOR` | `Green` | Colour for `rain` |
| `MATRIX_DEFAULT_SPEED` | `0.05` | Falling speed for `matrix` |
| `MATRIX_DEFAULT_COLOR` | `Green` | Colour for `matrix` |
| `MATRIX_DEFAULT_CHARSET` | `binary` | Character set for `matrix` (`binary`, `kana`, `ascii`) |

**`[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 |
| `GENPWD_DEFAULT_SYMBOLS` | `1` | Include symbols (0/1) |
| `GENPWD_DEFAULT_UPPERCASE` | `1` | Include uppercase letters (0/1) |
| `GENPWD_DEFAULT_LOWERCASE` | `1` | Include lowercase letters (0/1) |
| `GENPWD_DEFAULT_NUMBERS` | `1` | Include digits (0/1) |
| `PWDSCORE_DEFAULT_VERBOSE` | `0` | Set to `1` for detailed scoring output from `pwdscore` |

**`[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` |

**`[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) |
| `MYEXTIP_DEFAULT_URL` | `https://ip-api.com/json` | API endpoint used by `myextip` |

**`[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

The `[lang]` key `SET_LOCALE` accepts a comma-separated list of
`alias:locale` pairs. Each pair generates a function of that name at startup:

```ini
SET_LOCALE = fr:fr_FR.UTF-8, us:en_US.UTF-8
```

This creates `setfr` and `setus`. Use `setlocale <locale>` to switch to any
installed locale directly.

Set `DEFAULT_LANG` to one of the defined aliases to activate that locale
automatically at login:

```ini
DEFAULT_LANG = fr
```

If `DEFAULT_LANG` is set but does not match any alias in `SET_LOCALE`, a
warning is displayed and no locale change is applied.

### 4.4. Prompt theming

The prompt appearance is controlled by two mechanisms that are applied in order
(later values win):

1. **Theme file** — sets a base colour palette.
2. **`[prompt]` section** in `profile.conf` — per-key overrides on top of the theme.

**Selecting a theme:**

```ini
[prompt]
PROMPT_THEME     = dark          # bare name → profile.d/themes/dark.theme
PROMPT_THEME_DIR = ~/.mythemes   # optional: custom search directory
```

Built-in themes: `default`, `dark`, `light`, `solarized`, `solarized-light`,
`monokai`, `monochrome`, `abyss`, `plasma`, `adwaita`.

**Overriding individual prompt colour slots:**

```ini
[prompt]
PROMPT_COLOR_USER_FG = $ICyan
PROMPT_COLOR_DIR_FG  = $IYellow
```

The eleven 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 |
| `PROMPT_COLOR_ERR_BG` / `ERR_FG` / `ERR_MARK` | Error bar background / text / X mark |
| `PROMPT_COLOR_ROOT_FG` | Username colour when running as root |
| `PROMPT_COLOR_USER_FG` | Username@host colour for normal users |
| `PROMPT_COLOR_DIR_FG` | Working directory colour |

**Writing a custom theme file:**

Theme files live in `profile.d/themes/` and use the `.theme` extension. They
are **parsed, not executed** — no shell code runs. Only two value forms are
accepted:

```ini
# Colour variable reference (resolved from profile.d/disp.sh)
PROMPT_COLOR_DIR_FG = "$ICyan"

# Raw ANSI escape sequence (single block, 16-colour or 24-bit true-colour)
PROMPT_COLOR_BAR_BG = "\e[48;2;7;54;66m"
```

Any unknown key, unsafe value, or shell construct is discarded with a warning.
Theme files may also override the standard colour variables (`Black`, `Blue`,
`On_IBlack`, etc.) to remap the entire terminal palette used by `ls`, `grep`,
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,
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
log file containing the error. Cygwin users: please note that the bash
implementation in Cygwin regularly triggers bugs on advanced code that works
fine on Linux or BSD. Please do not send syntax error bug reports if you
have not tested the same code under a real Unix environment.

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
development version before starting your work.

Read [CONTRIBUTING.md](./doc/CONTRIBUTING.md) for code style conventions,
branch workflow, and how to submit a patch or pull request.

It's heavily recommended to use git to obtain the latest copy of the profile
tree. Make sure your git configuration is correct in order to contribute.
Please contact me to obtain push authorizations, or, if you want to submit a
patch, you can send it by mail to the maintainer of profile.

Code written in Python or Perl might be accepted as long as it is not
mobilizing a lot of dependencies (forget big frameworks). Anything that
requires installing packages not provided in a minimal Debian or CentOS
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.

Please check [https://www.geoffray-levasseur.org/profile](https://www.geoffray-levasseur.org/profile).

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