fatalerrors/profile
1
0
Fork 0
Code Issues Pull Requests Projects Releases 10 Wiki Activity

added documentation

Browse Source
This commit is contained in:
fatalerrors
2026-04-15 14:09:34 +02:00
parent 89e20993da
commit b3f909e287
5 changed files with 1035 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

366
README.md
View File

@@ -1,113 +1,323 @@
# profile
This project aims to create an advanced bash profile. It includes some aliases,
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 administrator but might satisfy some regular users.
targeted to system administrators but might satisfy some regular users.
## 1. Getting started
## 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):
```
directory. You will have to modify your `~/.bashrc` and/or `~/.profile` file to
add at the end (preferably):
```bash
source <installpath>/profile/profile.sh
```
It's not recommended to load that profile in /etc/profile as the users' .bashrc
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. What's the purpose?
profile is giving access to numerous functions, aliases and to an advanced
prompt. Here is a non-exhaustive list of what we have:
- A bar style prompt with hour, execution time and exit code of the last
command;
- clean: erase after confirmation any backup file, possibly recursively;
- dwl: a curl/wget/fetch download wrapper;
- pkgs: search for the given pattern in the installed packages name;
- expandlist: usefull in scripts, it expand any expression using wildcards into
the corresponding list of file and directories;
- genpwd: generate one or more random secure password;
- gpid: give the list of PID matching the given process name;
- help: display the list of available function and basic use;
- isipv4: tell if the given parameter is a valid IPv4 address;
- isipv6: tell if the given parameter is a valid IPv6 address;
- ku: kill all the processes owned by the given user name or ID;
- mcd: create a directory and immediately move into it;
- meteo: display weather forecast information;
- myextip: get informations about your public IP;
- ppg: look for the given patern in the running processes;
- rain: console screensaver with rain effect;
- rmhost: remove the given host (name or IP) to the list of SSH known host;
- rmspc: in the current directory it replace all the spaces in filenames with a
underscore caracter (or any other given in option);
- setc: set locale on standard C;
- setfr: set locale on French;
- settrace: allow the debugging of any script by showing a backtrace in case of
error;
- setus: set locale on US English;
- showinfo: display basic informations about the host;
- ssr: root ssh login to the given host;
- taz: a universal command to compress files and directories, possibly several
at once;
- utaz: a utility that smartly uncompress many archives at once, creating a
directory only if needed;
- ver: show profile version.
## 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. Configuration
Some functions might have configurable default behaviour. You can create a
profile.conf file to configure those default behaviour. You should have a look
at the doc/profile.conf.example to see the list of available options. The
configuration file is located in the same directory as profile.sh file.
### 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.
## 4. Contact and more information
### 4.1. New users
This project is very new in terms of publication, and I have no idea of who will
use it, if any does. If you use (or plan to use) ```profile```, I'll be very
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!
### 3.2. Functions reference
### 4.2. Bugs
| 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.
### 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 trigger it, if any, and the
log file containing the error. Cygwin users: please note that bash
implementation in Cygwin triggers regularly bugs on advanced code that triggers
nothing with Linux or BSD. Please do not send synthax error bug repports if you
didn't test the same code in the same conditions using a real Unix.
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.
Please check the to-do list before sending any feature request, as it might
have already be requested.
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.
### 4.3. How to contribute?
### 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.
It's heavily recommended to use git to obtain the latest copy of 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 init.sh.
Read [CONTRIBUTING.md](./doc/CONTRIBUTING.md) for code style conventions,
branch workflow, and how to submit a patch or pull request.
Code written in Python or Perl might be accepted as long as it's not mobilizing
a lot of dependencies (forget big framework). Anything that need the
installation of packages not provided in minimal Debian or CentOS installation
will be probably rejected.
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.
### 4.4. License, website, and maintainer
Everything except configuration files is licensed under BSD-3 license. Please
check license file allong this one.
### 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).
Note that this website is still under construction and needs some more care.
You can mail author to fatalerrors \<at\> geoffray-levasseur \<dot\> org.
You can mail the author at fatalerrors \<at\> geoffray-levasseur \<dot\> org.
-----------------------------------------------------------------------------
Documentation (c) 2021-2022 Geoffray Levasseur.
Documentation (c) 2021-2026 Geoffray Levasseur.
This file is distributed under3-clause BSD license. The complete license
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