https://github.com/pocco81/mini-prompt
๐ฆ Minimal and versatile bash prompt
https://github.com/pocco81/mini-prompt
bash-prompt bash-script minimal prompt shell-prompt shellcheck
Last synced: 6 months ago
JSON representation
๐ฆ Minimal and versatile bash prompt
- Host: GitHub
- URL: https://github.com/pocco81/mini-prompt
- Owner: pocco81
- License: gpl-3.0
- Created: 2021-11-14T03:44:33.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-11-22T14:41:33.000Z (almost 4 years ago)
- Last Synced: 2024-10-30T13:08:53.164Z (12 months ago)
- Topics: bash-prompt, bash-script, minimal, prompt, shell-prompt, shellcheck
- Language: Shell
- Homepage:
- Size: 125 KB
- Stars: 40
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
๐ฆ MiniPrompt!
Minimal and versatile bash prompt
## About
MiniPrompt is a minimal Bash prompt that aims to be as lightweight as possible while still being feature rich and user friendly enough to appeal to most users.
## ๐ Features
- Colored exit status
- Easily configurable
- Fully customizable: colors, symbols, the prompt itself, and more...
- Better history
- Better completion
- Directory colors support
- Trimming path
- Various extensions
- Git
- Kubernetes
- SSH
- IP address
- WIFI
- Package versions
- Extensions can be toggled on and off on the fly
## ๐ค Usage
### ๐ฆ Installation
Make sure you have the following programs installed in your system:
- GNU Make
- `git`
- `npm` (for the npm installer)
- General utilities like `grep`, `sed`, `awk`, ...
- A patched [Nerd Font](https://www.nerdfonts.com/) (optional)
#### NPM
```
$ npm install --global miniprompt.sh
```
> If it throws an error then run the command with `sudo`
#### Manual
```sh
$ git clone git@github.com:Pocco81/MiniPrompt.git && cd MiniPrompt
$ make install
```
> Installs the prompt under your local bins: `~/.local/bin`. Make sure this directory is in your `$PATH`; if it's not, paste this into your `~/.bashrc`:
```sh
export PATH=$PATH:"$HOME/.local/bin"
```
#### AUR
```sh
๐ท๐ Under dev
```
### ๐ง Setup
Two things:
1. Enable the prompt in your `~/.bashrc`
2. Configure it
To enable the prompt paste this into your `~/.bashrc`:
```sh
alias mp="source miniprompt"
mp
```
After that, feel free to customize the prompt to your like using the `conf.toml` file (located under `${XDG_CONFIG_HOME}/miniprompt/conf.toml`. If the `$XDG_CONFIG_HOME` env var is not set then it'll be assumed to be `$HOME/.config/`).
Here is the [default config](https://github.com/Pocco81/MiniPrompt/blob/main/config/conf.toml):
```toml
# MiniPrompt's config file
[behaviour]
colored_exit_status = true # prettify the exit status of the previous command
dirtrim = 2 # trim the CWD to only show x number of dirs
enhanced_autocompletion = true # completion maps, tilde expansion, mark directories, ...
enhanced_history_format = true # better format for your shell history: [%Y-%m-%d %T]
dircolors = true # color directories
[primary_prompt]
prefix = "\[\e]0;\w\a\]" # prompt prefix
ps_content = "\w " # the actual content of your prompt
ps_suffix = "โ " # after the ps_content
normal_color = "nc" # the color text is defaulted to
error_symbol = "โ" # symbol to use after the previous command failed
failed = "red" # $error_mark's color after the previous command executed successfully
[extensions]
ext_git = false # enable git extension (shows current working branch)
ext_ssh = false # enable ssh expansion (shows @)
ext_package = false # enable package expansion (shows project's current version)
ext_kubernetes = false # enable kubernetes extension (shows kubernetes' current context)
ext_ip = false # enable kubernetes extension (shows kubernetes' current context)
ext_wifi = false
git_struct = "๎ฅ " # structure of the integration
ssh_struct = "๏ " # structure of the integration
package_struct = "๏ฎ v " # structure of the integration
ip_struct = "๏ค " # structure of the integration
wifi_struct = "๏ชจ " # structure of the integration
hierarchy = "ssh, git, ip, wifi, package" # order in which the extensions are displayed
```
#### Customizing!
##### Showcase
```
ps_content = "\w \@ \n๏ฎ \u "
```
```
ps_content = "๎ถ\A \w๎ด "
ps_suffix = "๏ " # after the ps_content
```
```sh
[primary_prompt]
ps_content = "\w " # the actual content of your prompt
ps_suffix = "\nโ " # after the ps_content
[extensions]
git_struct = "๎ถ๎ฅ ๎ด " # structure of the integration
package_struct = "๎ถ๏ฎ v๎ด " # structure of the integration
```
##### Prompt
The prompt itself can be changed modifying the `ps_content` and `ps_suffix` variables. Apart from giving your prompt different colors using the [tags](#tags), you can also modify the information displayed using the following built-in Bash options:
| Opts | Description |
| ------------ | ------------------------------------------------------- |
| `\a` | A bell character |
| `\d` | Date (day/month/date) |
| `\D{format}` | Date but following the system's time format |
| `\e` | Escape character |
| `\h` | Hostname (short) |
| `\H` | Full hostname (domain name) |
| `\j` | Number of jobs being managed by the shell |
| `\l` | The basename of the shells terminal device |
| `\n` | New line |
| `\r` | Carriage return |
| `\s` | The name of the shell |
| `\t` | Time (hour:minute:second) |
| `\@` | Time, 12-hour AM/PM |
| `\A` | Time, 24-hour, without seconds |
| `\u` | Current username |
| `\v` | BASH version |
| `\V` | Extra information about the BASH version |
| `\w` | Current working directory |
| `\W` | The basename of the working directory |
| `\!` | Lists this commandโs number in the history |
| `\#` | This commandโs command number |
| `\$` | Specifies whether the user is root (#) or otherwise ($) |
| `\\` | Backslash |
| `\[` | Start a sequence of non-displayed characters |
| `\]` | Close or end a sequence of non-displayed characters |
##### Structs
Structs define the structure of the extensions. You can use tags to customize the structs further. However, there is an additional tag called ``, which is the output of the extension. Say you are using the git extension:
```sh
git_struct = "๎ฅ "
```
This will display:
```sh
๎ฅ dev
```
Because ``, in this case, displays the current working branch.
##### Tags
| Tag | Description |
| ------------ | -------------------------------------- |
| `` | Makes text following it gray |
| `` | Makes text following it red |
| `` | Makes text following it green |
| `` | Makes text following it blue |
| `` | Makes text following it cyan |
| `` | Makes text following it yellow |
| `` | Makes text following it magenta |
| `` | Makes text following it white |
| `` | Removes the color of text following it |
You can also give some properties to the colors by using modifiers and appending them at the end of the color (e.g. ``):
| Modifier | Description |
| -------- | ----------- |
| `_br` | bright |
| `_dm` | dim |
| `_it` | italic |
| `_un` | underlined |
| `_bl` | blinking |
| `_re` | inverted |
### ๐ฟ Utilization
#### On the fly commands
On the previous step we created the alias `mp`, which we will be using to run commands for MiniPrompt. Use `mp --help` to see the available commands. Here is a quick example enabling the Git extension:
```sh
$ mp git enable
# you can shorten it as: mp gt e
```
#### Reloading the prompt
After changing the config file you can reload the prompt using the same alias, but without any flags:
```sh
$ mp
```
#### Dependencies for extensions
| Extension | Dependencies |
| --------- | ------------ |
| Git | `git` |
| SSH | `openssh` |
| Package | `npm` |
| Wifi | `nmcli` |
| IP | `ip` |
## ๐ FAQ
- Q: **_"If I don't have a config file, will MiniPrompt create one for me?"_**
- A: No, settings will simply be assumed from default values.
- Q: **_"Why does the alias created for the prompt needs to be sourced?"_**
- A: Because you can't export env vars from a shell script unless it's sourced, so [this](https://stackoverflow.com/questions/16618071/can-i-export-a-variable-to-the-environment-from-a-bash-script-without-sourcing-i) is the best solution.
## ๐ License
MiniPrompt is released under the GPL v3.0 license. It grants open-source permissions for users including:
- The right to download and run the software freely
- The right to make changes to the software as desired
- The right to redistribute copies of the software
- The right to modify and distribute copies of new versions of the software
For more convoluted language, see the [LICENSE file](https://github.com/Pocco81/MiniPrompt/blob/main/README.md).
# ๐ TO-DO
**High Priority:**
- Publish to the AUR?
**Low Priority:**
- None
Enjoy!