sld-admin/Modular-Bashrc-Manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a40e5dfba829bbf85a1ba36c82395c7fd43462df
Modular-Bashrc-Manager/README.md
T

16 KiB
Raw Blame History

⚡ Modular Bashrc Manager

A modern, modular, and blazing-fast system to organize, manage, and scale your Bash configuration in Linux & macOS.

Language: English Traduzione: Italiano Shell Script License: GPL v3 Platform: Linux / macOS Gitea

🇬🇧 English • 🇮🇹 Italiano

📑 Table of Contents

🔍 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 with line numbering (brc-script -p)

✨ 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)
    View script contents with colored status headers and line numbering without opening an external editor (brc-script -p <id|name>).

  • 🖥️ 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:

~/.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:

    git clone https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager.git
cd Modular-Bashrc-Manager/installer

  2. Run the installer:

    chmod +x brc-script-install.sh
./brc-script-install.sh

  3. Reload your shell:

    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 -p, -v, --cat, --show, cat <id|name ...> Prints script code with line numbers without opening an editor
Enable -e, --enable, enable <id|name ...> Activates one or more scripts by creating symlinks in scripts-enabled/
Disable -d, --disable, disable <id|name ...> 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 <id|name> Opens a script in $EDITOR (or vim) and allows renaming
Remove -r, --remove, remove <id|name ...> 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

brc-script -l

Output preview:

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

# 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

# Disable by IDs
brc-script -d 2 4 5

# Disable by names
brc-script -d 03_bashboard 04_aliases

4. Previewing Script Code Directly in Terminal

Inspect what a script does before enabling it:

# Preview using numeric ID
brc-script -p 4

# Preview using script name
brc-script --cat 03_bashboard

5. Creating a New Custom Script

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

# 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: 
    brc-script -c
  2. Enter the script name (e.g. my-docker-tools).
  3. Add your custom functions, aliases, and environment variables:
#!/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!"
}
  1. Save and exit the editor.
  2. Enable your new module: 
    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:

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:

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:

cp ~/bashrc-backup-* ~/.bashrc

3. Where are removed scripts stored?

When you delete a script with brc-script -r <id|name>, it is never permanently deleted; it is timestamped and safely placed in:

~/.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:

export EDITOR="nano"   # or "code", "vim", "nvim", "micro"

📄 License & Author

Made with ❤️ by Simone Cusano. If you find this project helpful, feel free to star and share it!
Reference in New Issue View Git Blame Copy Permalink