# โก Modular Bashrc Manager
**A modern, modular, and blazing-fast system to organize, manage, and scale your Bash configuration in Linux & macOS.**
[](#)
[](README.it.md)
[](https://www.gnu.org/software/bash/)
[](LICENSE)
[](https://www.kernel.org/)
[](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
[๐ฌ๐ง **English**](README.md) โข [๐ฎ๐น **Italiano**](README.it.md)
---
## ๐ Table of Contents
- [Overview](#-overview)
- [Why Modular Bashrc Manager?](#-why-modular-bashrc-manager)
- [Key Features](#-key-features)
- [Architecture & Loading Flow](#-architecture--loading-flow)
- [Installation & Quick Start](#-installation--quick-start)
- [Automated Installation](#automated-installation)
- [What the Installer Does](#what-the-installer-does)
- [CLI Reference (`brc-script`)](#-cli-reference-brc-script)
- [Command Cheat Sheet](#command-cheat-sheet)
- [Usage Examples](#usage-examples)
- [Included Default Modules](#-included-default-modules)
- [Creating Custom Modules](#-creating-custom-modules)
- [Extra Utilities (`ccecho`)](#-extra-utilities-ccecho)
- [Supported Distributions](#-supported-distributions)
- [Troubleshooting & FAQ](#-troubleshooting--faq)
- [License & Author](#-license--author)
---
## ๐ Overview
**Modular Bashrc Manager** replaces the traditional, chaotic, single-file `~/.bashrc` with a clean, decoupled, and modular architecture inspired by the `available`/`enabled` paradigm used by Debian, Apache, and Nginx.
Instead of stuffing hundreds of aliases, functions, exports, and prompt customizations into one monolithic file, you break your shell configuration into distinct, self-contained scripts that can be enabled, disabled, previewed, created, or safely upgraded with a single command.
```
~/.bashrc โโโถ Loader โโโถ ~/.bashrc.d/scripts-needed/ (Core engine & utilities)
โโโถ ~/.bashrc.d/scripts-enabled/ (Active customizations)
```
---
## ๐ก Why Modular Bashrc Manager?
| Monolithic `~/.bashrc` | With Modular Bashrc Manager |
| :--- | :--- |
| โ Hundreds of lines in a single messy file | โ
Decoupled single-purpose scripts |
| โ Hard to debug errors and test changes | โ
Enable or disable modules instantly (`brc-script -e` / `-d`) |
| โ Risk of accidentally breaking the whole shell | โ
Safe symlink-based activation and automatic backups |
| โ Impossible to share individual snippets | โ
Modular files ready to share, version-control, or reuse |
| โ Manually editing files to preview snippets | โ
Instant terminal preview or cat (`brc-script -p` / `-v`) |
---
## โจ Key Features
- ๐ **Intelligent Multi-Distro Installer**
Auto-detects your operating system package manager (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`, `brew`) and automatically installs required dependencies (`jq`, `curl`).
- ๐ **Zero-Loss Safe Migration**
Creates a timestamped backup of your current `~/.bashrc` and automatically migrates your pre-existing customizations into `00_default.sh` so you lose **nothing**.
- โก **Multi-Script Batch Management**
Enable, disable, preview, or remove multiple scripts at the same time using either their numeric ID or script name (e.g. `brc-script -e 1 3 4` or `brc-script -d 03_bashboard 04_aliases`).
- ๐๏ธ **Instant Script Code Preview & Cat (`-p` / `-v`)**
Inspect script contents directly in the terminal without opening an external editor. Use `brc-script -p ` for preview with colored headers and line numbers, or `brc-script -v ` (or `--cat`) for clean code cat without line numbers.
- ๐ฅ๏ธ **Smart System Bashboard**
Includes `03_bashboard.sh`, a fast MOTD-style dashboard showing CPU, RAM, disk usage, uptime, distro details, IP addresses, package update counts, and **automatic dynamic discovery of Cockpit Web UI**.
- ๐ฟ **Git CLI Status Highlighting**
Includes dynamic prompt hooks (`01_git-cli-highlitgh.sh` & `02_git-cli-highlitgh-root.sh`) that show current Git branch, staged (`+`), modified (`M:`), untracked (`N:`), and remote sync (`โ`/`โ`) status directly in your prompt.
- ๐ **Gitea Updates & Safe Upgrades**
Check for official updates with `brc-script -u` and safely upgrade core files with `brc-script --upgrade` without touching personal configurations or `00_default.sh`.
- ๐จ **Built-in `ccecho` Styling Utility**
Lightweight utility for terminal coloring and styling (bold, underline, dim, blink, colors, backgrounds).
---
## ๐๏ธ Architecture & Loading Flow
When your shell starts, `~/.bashrc` executes a minimal loader loop that sources modules in a deterministic order:
```text
~/.bashrc.d/
โโโ .version # Current commit/version tracking hash
โโโ .update_cache # Cache for passive Gitea update checks
โโโ scripts-needed/ # Essential engine scripts (Always loaded first)
โ โโโ brc-script.sh # Main CLI manager logic & functions
โ โโโ ccecho.sh # Colored terminal printing engine
โ
โโโ scripts-available/ # All installed scripts (Library of modules)
โ โโโ 00_default.sh # Your personal migrated config (Protected)
โ โโโ 01_git-cli-highlitgh.sh # Git branch & status prompt (User)
โ โโโ 02_git-cli-highlitgh-root.sh # Git branch & status prompt (Root/User color-coded)
โ โโโ 03_bashboard.sh # System metrics & Cockpit auto-detection
โ โโโ 04_aliases.sh # General utility aliases
โ
โโโ scripts-enabled/ # Symlinks pointing to active scripts in scripts-available/
โ โโโ 00_default.sh -> ../scripts-available/00_default.sh
โ โโโ 03_bashboard.sh -> ../scripts-available/03_bashboard.sh
โ
โโโ scripts-removed/ # Recycle bin with timestamped backups of removed scripts
```
### Loading Order:
1. All files in `scripts-needed/*.sh` are sourced sequentially.
2. All active symlinks in `scripts-enabled/*.sh` are sourced alphabetically.
---
## ๐ฅ Installation & Quick Start
### Automated Installation
1. **Clone the repository:**
```bash
git clone https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager.git
cd Modular-Bashrc-Manager/installer
```
2. **Run the installer:**
```bash
chmod +x brc-script-install.sh
./brc-script-install.sh
```
3. **Reload your shell:**
```bash
refresh-brc
# or: source ~/.bashrc
```
> [!TIP]
> You can run the installer as a normal user or as `root` to configure any user on the system.
### What the Installer Does:
- ๐ Detects OS distribution and installs `jq` and `curl` automatically.
- ๐พ Creates a timestamped backup of your current `~/.bashrc` (e.g. `~/bashrc-backup-2026-08-26_16-00-00`).
- ๐ Migrates existing `.bashrc` lines into `~/.bashrc.d/scripts-available/00_default.sh` and enables it immediately.
- ๐งน Replaces `~/.bashrc` with the clean, non-intrusive modular loader block.
- ๐ฆ Deploys the core logic to `scripts-needed/` and default modules to `scripts-available/`.
- ๐ท๏ธ Initializes `.version` with the latest Git commit hash.
---
## ๐ป CLI Reference (`brc-script`)
`brc-script` is the central command-line utility for administering your modular configuration.
### Command Cheat Sheet
| Action | Flags / Aliases | Arguments | Description |
| :--- | :--- | :--- | :--- |
| **List** | `-l`, `--list`, `list` | *none* | Lists all scripts with IDs, names, and active status (`-` in blue) |
| **Preview (Numbered)** | `-p`, `--preview`, `preview` | `` | Prints script code with line numbers and status headers |
| **Cat / View (Plain)** | `-v`, `--cat`, `--view`, `--show`, `cat`, `view` | `` | Prints clean script code without line numbers |
| **Enable** | `-e`, `--enable`, `enable` | `` | Activates one or more scripts by creating symlinks in `scripts-enabled/` |
| **Disable** | `-d`, `--disable`, `disable` | `` | Deactivates one or more scripts by removing symlinks |
| **Enable All** | `-ea`, `--enable-all`, `enable-all` | *none* | Enables all available scripts at once |
| **Disable All** | `-da`, `--disable-all`, `disable-all` | *none* | Disables all enabled scripts at once |
| **Create** | `-c`, `--create`, `create` | *none* | Interactive wizard to create a new script template and open it in `$EDITOR` |
| **Modify** | `-m`, `--modify`, `modify` | `` | Opens a script in `$EDITOR` (or `vim`) and allows renaming |
| **Remove** | `-r`, `--remove`, `remove` | `` | Safely moves script(s) to `scripts-removed/` with a timestamp |
| **Update** | `-u`, `--update`, `update` | *none* | Queries Gitea repository for new commits/updates |
| **Upgrade** | `--upgrade`, `upgrade` | *none* | Safely upgrades core scripts and default modules without altering your custom code |
| **Reload** | `refresh-brc` | *none* | Immediately reloads `~/.bashrc` in the current shell session |
---
### Usage Examples
#### 1. Listing All Available Modules
```bash
brc-script -l
```
*Output preview:*
```text
------------------------------------
Scripts List
------------------------------------
1) 00_default.sh -
2) 01_git-cli-highlitgh.sh
3) 02_git-cli-highlitgh-root.sh
4) 03_bashboard.sh -
5) 04_aliases.sh
------------------------------------
'-' (blue) = Active / Enabled
------------------------------------
```
#### 2. Enabling Multiple Scripts in One Command
You can pass numbers, names with `.sh`, or names without `.sh`:
```bash
# Enable by numerical IDs
brc-script -e 2 5
# Enable by script names
brc-script -e 01_git-cli-highlitgh 04_aliases
```
#### 3. Disabling Multiple Scripts
```bash
# Disable by IDs
brc-script -d 2 4 5
# Disable by names
brc-script -d 03_bashboard 04_aliases
```
#### 4. Previewing and Catting Script Code Directly in Terminal
Inspect what a script does before enabling it:
```bash
# Preview with line numbers and header info
brc-script -p 4
brc-script --preview 03_bashboard
# Cat clean code without line numbers (easy to copy & paste)
brc-script -v 4
brc-script --cat 03_bashboard
```
#### 5. Creating a New Custom Script
```bash
brc-script -c
```
Prompts for a script name (e.g. `docker-shortcuts`), sets up a boilerplate header, and opens it directly in `$EDITOR` (or `vim`).
#### 6. Checking and Performing Upgrades
```bash
# Check if updates are available on Gitea
brc-script -u
# Upgrade core engine and default templates
brc-script --upgrade
```
> [!NOTE]
> `brc-script --upgrade` will **never** overwrite your `00_default.sh` or custom scripts. Only standard upstream modules and `scripts-needed/` utilities are updated.
---
## ๐ฆ Included Default Modules
### `00_default.sh` โ Your Personal Migrated Configuration
- **Purpose:** Houses all your existing aliases, functions, environment variables, and `PATH` exports migrated during installation.
- **Safety:** **Strictly protected**. Upgrades will never touch or overwrite this file.
### `01_git-cli-highlitgh.sh` โ Git Status Prompt (User)
- **Purpose:** Adds a clean, color-coded Git branch and status indicator to your bash prompt:
- Branch name in **Green** (clean) or **Purple** (dirty).
- `+N`: Staged files count (Green).
- `M:N`: Modified files count (Yellow).
- `N:N`: Untracked files count (Red).
- `โN` / `โN`: Commits ahead / behind remote (Cyan).
### `02_git-cli-highlitgh-root.sh` โ Git Status Prompt (Root / Multi-User)
- **Purpose:** High-visibility Git prompt tailored for multi-user/root environments. Displays red alert styling for `root` (`#`) and green/blue for normal users (`>`).
### `03_bashboard.sh` โ Terminal MOTD & Cockpit Discovery
- **Purpose:** Displays an interactive system dashboard upon login:
- Distro details and Hostname
- Local and Public IP addresses
- System Uptime & Load
- Memory (RAM) & Disk usage with color-coded thresholds
- CPU Temperature (with VM detection)
- Pending Package Updates count (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`)
- **Dynamic Cockpit Web UI Detection:** Detects if Cockpit is installed and running, extracts its listening port from configuration/sockets, and displays the direct URL.
### `04_aliases.sh` โ Essential Aliases
- **Purpose:** Handy starting aliases (e.g., colorized directory listings).
---
## ๐ ๏ธ Creating Custom Modules
Creating your own modular script is simple:
1. Run the creator wizard:
```bash
brc-script -c
```
2. Enter the script name (e.g. `my-docker-tools`).
3. Add your custom functions, aliases, and environment variables:
```bash
#!/bin/bash
# ============================================================
# Modular Bashrc - my-docker-tools.sh
# ============================================================
# Custom aliases
alias dps="docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
alias dlogs="docker logs -f --tail=100"
# Custom function
dclean() {
ccecho -t byellow "Cleaning unused Docker containers and images..."
docker system prune -af --volumes
ccecho -t bgreen "Docker cleaned successfully!"
}
```
4. Save and exit the editor.
5. Enable your new module:
```bash
brc-script -e my-docker-tools
refresh-brc
```
---
## ๐จ Extra Utilities (`ccecho`)
Modular Bashrc Manager includes `ccecho`, a high-performance ANSI text formatting helper located in `scripts-needed/ccecho.sh`. You can use it in any of your custom scripts:
```bash
ccecho -t green -s bold "Operation succeeded!"
ccecho -t red -b black -s underline "Fatal Error: Connection refused"
```
### Available Options:
- **Text Colors (`-t` / `--text`):**
`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
*Bright variants:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
- **Background Colors (`-b` / `--bg`):**
`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
*Bright variants:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
- **Text Styles (`-s` / `--style`):**
`bold`, `dim`, `italic`, `underline`, `blink`, `reverse`, `hidden`, `strike`
---
## ๐ง Supported Distributions
Modular Bashrc Manager has been tested and includes native package detection for:
| Family | Distributions / Systems | Package Manager |
| :--- | :--- | :--- |
| **Debian** | Debian, Ubuntu, Linux Mint, Pop!_OS, Raspberry Pi OS | `apt` / `apt-get` |
| **Red Hat** | Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux | `dnf` / `yum` |
| **Arch** | Arch Linux, Manjaro, EndeavourOS | `pacman` |
| **SUSE** | openSUSE Leap, openSUSE Tumbleweed | `zypper` |
| **Alpine** | Alpine Linux (containers & servers) | `apk` |
| **macOS** | Apple macOS (Intel & Apple Silicon) | `brew` (Homebrew) |
---
## โ Troubleshooting & FAQ
### 1. I enabled a script, but new commands aren't working yet!
Run the reload command in your terminal:
```bash
refresh-brc
```
*(Or restart your terminal session).*
### 2. How do I restore my original `.bashrc`?
The installer automatically creates a timestamped backup before touching anything. To restore:
```bash
cp ~/bashrc-backup-* ~/.bashrc
```
### 3. Where are removed scripts stored?
When you delete a script with `brc-script -r `, it is never permanently deleted; it is timestamped and safely placed in:
```text
~/.bashrc.d/scripts-removed/
```
### 4. How can I change the default text editor for `brc-script`?
Set the `EDITOR` environment variable in your `00_default.sh`:
```bash
export EDITOR="nano" # or "code", "vim", "nvim", "micro"
```
---
## ๐ License & Author
- **Author:** Simone Cusano ([sld-server.org](https://sld-server.org))
- **Repository:** [https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
- **License:** GNU General Public License v3.0 ([GPL-3.0](LICENSE))
---
Made with โค๏ธ by Simone Cusano. If you find this project helpful, feel free to star and share it!