337 lines
15 KiB
Markdown
337 lines
15 KiB
Markdown
# 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 |
|
||
| `pkgs` | packages | Search for a pattern in installed package names (dpkg/rpm, 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 `[general]` 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.
|
||
|
||
### 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
|