From 4a7cdcc11f532415a9bc6e48eb8a61d5e1ea6093 Mon Sep 17 00:00:00 2001 From: steffen Date: Sun, 25 Jan 2026 00:14:21 +0000 Subject: [PATCH] Polish docs and repo hygiene --- .editorconfig | 18 ++++++ .github/workflows/shellcheck.yml | 20 +++++++ CONTRIBUTING.md | 22 ++++++++ README.md | 97 ++++++++++++++++++++++++-------- UNINSTALL.md | 35 ++++++++++++ libary.md => library.md | 0 6 files changed, 167 insertions(+), 25 deletions(-) create mode 100644 .editorconfig create mode 100644 .github/workflows/shellcheck.yml create mode 100644 CONTRIBUTING.md create mode 100644 UNINSTALL.md rename libary.md => library.md (100%) diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..67676e7 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,18 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[*.sh] +indent_style = space +indent_size = 2 + +[*.yml] +indent_style = space +indent_size = 2 diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml new file mode 100644 index 0000000..e3bc0f8 --- /dev/null +++ b/.github/workflows/shellcheck.yml @@ -0,0 +1,20 @@ +name: ShellCheck + +on: + push: + paths: + - "dotfiles/**/*.sh" + - ".github/workflows/shellcheck.yml" + pull_request: + paths: + - "dotfiles/**/*.sh" + - ".github/workflows/shellcheck.yml" + +jobs: + shellcheck: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: ludeeus/action-shellcheck@v2 + with: + scandir: dotfiles diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f8361b3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing + +Thanks for helping improve ps1-craft. Keep changes small, readable, and fast. + +## Style rules + +- Keep the prompt hot path fast (no external commands unless feature-gated). +- Use `printf` over `echo` for formatting. +- Quote variables and paths; avoid word-splitting. +- Maintain bash 3.2 compatibility for macOS. + +## Add a new theme or palette + +1) Update `dotfiles/ps1/ps1.sh` with the new colors/icons. +2) Add a screenshot under `images/themes/`. +3) Document it in `library.md` and `README.md`. + +## Testing + +- Run the installer script you changed. +- Open a new shell and verify the prompt renders. +- Run ShellCheck on `dotfiles/**/*.sh`. diff --git a/README.md b/README.md index f142a4d..0d9e504 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,31 @@ -# Bashrc Dotfiles — Global & Portable Bash Prompt +# ps1-craft — Global & Portable Bash Prompt Elegant, portable, and easy-to-install Bash prompt with seasonal palettes, time-aware emoji, and clean powerline structure. +## ⚡ 10-Second Demo + +```text +[Mon 14:32 steffen] ▶ +@host ~/ps1-craft ⟦main⟧ ✨ +``` + +Preview (Aurora seasonal): + +![Aurora (seasonal)](images/themes/season-winter.png) + --- ## ⚡ Quick Look -- Theme gallery + full specs: [Theme Library](libary.md) +- Theme gallery + full specs: [Theme Library](library.md) +- Install scope + rollback: [UNINSTALL.md](UNINSTALL.md) - Packs: Seasonal (auto), Contest, Holidays, Custom, Git - Layout order option: day-time-user, user-time, time-user, day-time - Optional git capsule across themes ## ✅ Requirements (Nerd Fonts) -This prompt relies on Nerd Font glyphs for the rounded separators. +This prompt relies on Nerd Fonts glyphs for the rounded separators. ```bash bash dotfiles/install/install-nerdfont.sh @@ -21,13 +33,29 @@ bash dotfiles/install/install-nerdfont.sh After install: -- Set your terminal font to JetBrainsMono Nerd Font (or any Nerd Font) +- Set your terminal font to JetBrainsMono Nerd Font (or any Nerd Fonts family) - Manual download: https://www.nerdfonts.com/font-downloads If you use a non‑Nerd font, the prompt falls back to ASCII/Unicode. --- +## ⚠️ Safety / Scope (global install) + +Linux/WSL installs are global and modify system files: + +- Writes `/etc/profile.d/ps1.sh` and `/etc/profile.d/banner.sh` +- Writes `/etc/ps1-season`, `/etc/ps1-style`, and `/etc/ps1-punchline` +- Adds a managed source block in `/etc/bash.bashrc` + +Rollback and uninstall steps live in [UNINSTALL.md](UNINSTALL.md). You can also disable per user: + +- `export DISABLE_GLOBAL_PS1=1` +- `export DISABLE_GLOBAL_BANNER=1` +- `touch ~/.config/ps1/disable` (PS1) or `touch ~/.config/ps1/disable-banner` (banner) + +--- + ## 🚀 Install ### 🐧 Linux / WSL (global, all users) @@ -35,13 +63,13 @@ If you use a non‑Nerd font, the prompt falls back to ASCII/Unicode. 1) Clone the repo: ```bash -git clone +git clone git@github.com:Hawolex/ps1-craft.git ``` 2) Enter the folder: ```bash -cd Bashrc +cd ps1-craft ``` 3) Run the global installer (auto-installs deps + prompts for punchline): @@ -57,13 +85,13 @@ sudo bash dotfiles/install/install-linux-global.sh 1) Clone the repo: ```bash -git clone +git clone git@github.com:Hawolex/ps1-craft.git ``` 2) Enter the folder: ```bash -cd Bashrc +cd ps1-craft ``` 3) Run the user installer: @@ -194,6 +222,12 @@ echo "Your punchline" | sudo tee /etc/ps1-punchline >/dev/null ## 🎛️ Themes & Style Packs +Terminology: + +- Theme = palette + emoji set +- Style = layout + separators +- Pack = a curated set of styles/themes + ### 🏁 Contest Pack The contest pack is a bold, DEFCON-ready set of five styles (Aurora, Neon, Forge, Circuit, Mono) with optional layout order. It always starts on a new line and ends with `@host - /path`. @@ -225,11 +259,13 @@ Custom styles add a small context badge when relevant (`ssh`, `ctr`, `git`). The Git theme adds a repo-aware capsule on line 2 that only appears inside a Git repo. The branch name is wrapped as `⟦branch⟧`, and status emojis reflect state: -- Clean: ✨ -- Dirty: 🔨 -- Staged: 📌 -- Untracked: 🧷 -- Stashed: 📦 +```text +Clean ✨ +Dirty 🔨 +Staged 📌 +Untracked 🧷 +Stashed 📦 +``` It uses the same two-block layout as Aurora, but focuses on signal and minimal noise for fast scanning. Use it when you want repo status on every command without a full VCS prompt. @@ -294,12 +330,16 @@ Meaning: ```text . -├── .context.json -├── contest-styles.json -├── images/ -│ ├── bash-pallete.png -│ └── contest.png -│ └── themes/ +├── .editorconfig +├── .github/ +│ └── workflows/ +│ └── shellcheck.yml +├── .gitignore +├── CONTRIBUTING.md +├── LICENSE +├── README.md +├── UNINSTALL.md +├── library.md ├── dotfiles/ │ ├── banner/ │ │ └── banner.sh @@ -310,7 +350,9 @@ Meaning: │ ├── install-linux-global.sh │ ├── install-macos-user.sh │ └── install-nerdfont.sh -└── README.md +└── images/ + ├── bash-pallete.png + └── themes/ ```
@@ -318,7 +360,7 @@ Meaning: Sometimes autodetection doesn’t work (e.g., on macOS without fontconfig): -Force Nerd Font glyphs: +Force Nerd Fonts glyphs: ```bash export PS1_FORCE_NF=1 @@ -335,6 +377,14 @@ Add these to your `~/.bashrc` or `~/.bash_profile`. --- +## ⚙️ Performance Notes + +- Git capsule work only runs inside a Git repo and only when enabled +- Large repos can slow status checks; disable with `PS1_GIT=0` or avoid the Git theme +- Prompt logic avoids external commands unless a feature is enabled (banner, git capsule) + +--- +
Disable prompt (per user) @@ -445,10 +495,7 @@ Palette reference: Want to help improve this project? -- Fork the repository -- Make your changes -- Open a merge request -- Please keep consistent colors and styles +- See [CONTRIBUTING.md](CONTRIBUTING.md) for style rules and how to add a new theme/palette --- diff --git a/UNINSTALL.md b/UNINSTALL.md new file mode 100644 index 0000000..34709bd --- /dev/null +++ b/UNINSTALL.md @@ -0,0 +1,35 @@ +# Uninstall + +## Linux / WSL (global) + +Remove installed files: + +```bash +sudo rm -f /etc/profile.d/ps1.sh /etc/profile.d/banner.sh +sudo rm -f /etc/ps1-season /etc/ps1-style /etc/ps1-punchline +``` + +Remove the managed block from `/etc/bash.bashrc`: + +```bash +sudo sed -i '/# >>> dotfiles (managed) >>>/,/# <<< dotfiles (managed) <<>> user ps1 (managed) >>>/,/# <<< user ps1 (managed) <<>> user ps1 (managed) >>>/,/# <<< user ps1 (managed) <<