Merge pull request #2308 from seefood/gaelic-plugins

Author: seefood

CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Bash-it is a collection of community Bash commands and scripts for Bash 3.2+, providing a framework for aliases, themes, plugins, and completions. It's structured as a modular system where components can be individually enabled or disabled.
+
+## Architecture
+
+### Core Components
+
+- **bash_it.sh**: Main entry point that initializes the framework
+- **lib/**: Core libraries providing utilities, logging, helpers, and appearance functions
+- **scripts/reloader.bash**: Component loader that sources enabled components
+- **install.sh**: Installation script with interactive and silent modes
+- **enabled/**: Symlinks to active components from available/ directories
+
+### Component Types
+
+1. **Aliases** (`aliases/available/`): Command shortcuts and convenience functions
+2. **Plugins** (`plugins/available/`): Extended functionality and integrations
+3. **Completions** (`completion/available/`): Tab completion definitions
+4. **Themes** (`themes/`): Prompt customizations and visual styles
+
+### Loading Order
+
+1. Libraries (except appearance)
+2. Global enabled directory
+3. Enabled aliases, plugins, completions
+4. Theme files (if BASH_IT_THEME is set)
+5. Custom files from BASH_IT_CUSTOM directory
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests using BATS (Bash Automated Testing System)
+test/run
+
+# Run specific test suites
+test/run test/bash_it test/completion test/plugins
+
+# Tests require git submodules to be initialized
+git submodule init && git submodule update
+```
+
+### Linting and Code Quality
+
+The project uses a gradual pre-commit system implementation via `clean_files.txt` allow-list:
+
+```bash
+# Run pre-commit hooks only on allow-listed clean files
+./lint_clean_files.sh
+
+# Run pre-commit hooks on all files (for testing new coverage)
+pre-commit run --all-files
+
+# Manual shellcheck on bash files
+shellcheck **/*.bash
+
+# Format shell scripts
+shfmt -w **/*.bash
+```
+
+**Gradual Linting System**:
+- `clean_files.txt`: Allow-list of files/directories that pass all linting rules
+- `lint_clean_files.sh`: Runs pre-commit hooks only on allow-listed files
+- When modifying files NOT in `clean_files.txt`, ensure they pass linting before adding them to the allow-list
+- Before creating a PR, add newly cleaned files to `clean_files.txt` to expand coverage
+- This system allows gradual improvement of code quality across the large codebase
+
+**Vendor Directory Policy**:
+- Files in `vendor/` are treated as immutable external dependencies
+- Pre-commit hooks exclude vendor files via `.pre-commit-config.yaml` global exclude pattern
+- `clean_files.txt` does not include vendor shell scripts, only `.gitattributes`
+- CI and local linting will skip vendor files entirely
+
+### Component Management
+```bash
+# Enable/disable components
+bash-it enable alias git
+bash-it enable plugin history
+bash-it enable completion docker
+
+# Show available components
+bash-it show aliases
+bash-it show plugins  
+bash-it show completions
+
+# Search components
+bash-it search docker
+```
+
+## Key Configuration
+
+### Environment Variables
+- `BASH_IT`: Base directory path
+- `BASH_IT_THEME`: Active theme name
+- `BASH_IT_CUSTOM`: Custom components directory
+- `BASH_IT_LOG_PREFIX`: Logging prefix for debug output
+
+### File Structure Conventions
+- Available components: `{type}/available/{name}.{type}.bash`
+- Enabled components: `{type}/enabled/{name}.{type}.bash` (symlinks)
+- Custom components: `custom/{name}.bash`
+- Themes: `themes/{name}/`
+
+## Development Guidelines
+
+### Component Development
+- Use composure metadata: `about`, `group`, `author`, `example`
+- Follow naming convention: `{name}.{type}.bash`
+- Test components before submitting
+- Components should be modular and not conflict with others
+
+### Testing Components
+- Each component type has dedicated test files in `test/`
+- Use BATS framework for shell script testing
+- Test files follow pattern: `{component}.bats`
+
+### Code Standards
+- Use shellcheck for linting
+- Follow existing code style in the repository
+- Add appropriate metadata using composure functions
+- Components should handle missing dependencies gracefully

aliases/available/general.aliases.bash

@@ -2,6 +2,19 @@
 # shellcheck source-path=SCRIPTDIR
 about-alias 'general aliases'
 
+if command ls --color -d . &> /dev/null; then
+	alias ls='ls --color=auto'
+	# BSD `ls` doesn't need an argument (`-G`) when `$CLICOLOR` is set.
+fi
+
+# List directory contents
+alias sl=ls
+alias la='ls -AF' # Compact view, show hidden
+alias ll='ls -Al'
+alias l='ls -A'
+alias l1='ls -1'
+alias lf='ls -F'
+
 alias _='sudo'
 
 # colored grep
@@ -58,7 +71,12 @@ alias rd='rmdir'
 alias rmrf='rm -rf'
 
 # Shorten extract
-alias xt='extract'
+_command_exists 'extract' \
+	&& alias xt='extract'
+
+# sudo editors
+alias svim='sudo "${VISUAL:-vim}"'
+alias snano='sudo "${ALTERNATE_EDITOR:-nano}"'
 
 # Display whatever file is regular file or folder
 function catt() {

bash_it.sh

@@ -22,11 +22,9 @@ _bash_it_library_finalize_hook=()
 # We need to load logging module early in order to be able to log
 source "${BASH_IT}/lib/log.bash"
 
-# libraries, but skip appearance (themes) for now
-_log_debug "Loading libraries(except appearance)..."
-APPEARANCE_LIB="${BASH_IT}/lib/appearance.bash"
+# Load libraries
+_log_debug "Loading libraries..."
 for _bash_it_main_file_lib in "${BASH_IT}/lib"/*.bash; do
-	[[ "$_bash_it_main_file_lib" == "$APPEARANCE_LIB" ]] && continue
 	_bash-it-log-prefix-by-path "${_bash_it_main_file_lib}"
 	_log_debug "Loading library file..."
 	# shellcheck disable=SC1090
@@ -55,10 +53,14 @@ if [[ -n "${BASH_IT_THEME:-}" ]]; then
 	source "${BASH_IT}/themes/base.theme.bash"
 
 	BASH_IT_LOG_PREFIX="lib: appearance: "
-	# appearance (themes) now, after all dependencies
-	# shellcheck source=SCRIPTDIR/lib/appearance.bash
-	source "$APPEARANCE_LIB"
-	BASH_IT_LOG_PREFIX="core: main: "
+	# shellcheck disable=SC1090
+	if [[ -f "${BASH_IT_THEME}" ]]; then
+		source "${BASH_IT_THEME}"
+	elif [[ -f "$CUSTOM_THEME_DIR/$BASH_IT_THEME/$BASH_IT_THEME.theme.bash" ]]; then
+		source "$CUSTOM_THEME_DIR/$BASH_IT_THEME/$BASH_IT_THEME.theme.bash"
+	elif [[ -f "$BASH_IT/themes/$BASH_IT_THEME/$BASH_IT_THEME.theme.bash" ]]; then
+		source "$BASH_IT/themes/$BASH_IT_THEME/$BASH_IT_THEME.theme.bash"
+	fi
 fi
 
 _log_debug "Loading custom aliases, completion, plugins..."

clean_files.txt

@@ -23,6 +23,7 @@ hooks/
 lib/
 plugins/
 scripts/
+template/
 test/
 
 # root files
@@ -32,6 +33,7 @@ bash_it.sh
 clean_files.txt
 install.sh
 lint_clean_files.sh
+uninstall.sh
 
 # themes
 #

docs/installation.rst

@@ -6,8 +6,8 @@ Installation
 
 #. Check out a clone of this repo to a location of your choice, such as
    ``git clone --depth=1 https://github.com/Bash-it/bash-it.git ~/.bash_it``
-#. Run ``~/.bash_it/install.sh`` (it automatically backs up your ``~/.bash_profile`` or ``~/.bashrc``\ , depending on your OS)
-#. Edit your modified config (\ ``~/.bash_profile`` or ``~/.bashrc``\ ) file in order to customize Bash-it.
+#. Run ``~/.bash_it/install.sh`` (it automatically backs up your ``~/.bashrc``\ )
+#. Edit your modified config (\ ``~/.bashrc``\ ) file in order to customize Bash-it.
 #. Check out available aliases, completions, and plugins and enable the ones you want to use (see the next section for more details).
 
 Install Options
@@ -18,7 +18,7 @@ The install script can take the following options:
 
 * ``--interactive``\ : Asks the user which aliases, completions and plugins to enable.
 * ``--silent``\ : Ask nothing and install using default settings.
-* ``--no-modify-config``\ : Do not modify the existing config file (\ ``~/.bash_profile`` or ``~/.bashrc``\ ).
+* ``--no-modify-config``\ : Do not modify the existing config file (\ ``~/.bashrc``\ ).
 * ``--append-to-config``\ : Back up existing config file and append bash-it templates at the end.
 
 When run without the ``--interactive`` switch, Bash-it only enables a sane default set of functionality to keep your shell clean and to avoid issues with missing dependencies.
@@ -28,16 +28,14 @@ When you run without the ``--no-modify-config`` switch, the Bash-it installer au
 Use the ``--no-modify-config`` switch to avoid unwanted modifications, e.g. if your Bash config file already contains the code that loads Bash-it.
 
 **NOTE**\ : Keep in mind how Bash loads its configuration files,
-``.bash_profile`` for login shells (and in macOS in terminal emulators like `Terminal.app <http://www.apple.com/osx/apps/>`_ or
-`iTerm2 <https://www.iterm2.com/>`_\ ) and ``.bashrc`` for interactive shells (default mode in most of the GNU/Linux terminal emulators),
-to ensure that Bash-it is loaded correctly.
+``.bash_profile`` for login shells and ``.bashrc`` for interactive shells, to ensure that Bash-it is loaded correctly.
 A good "practice" is sourcing ``.bashrc`` into ``.bash_profile`` to keep things working in all the scenarios.
 To achieve this, you can add this snippet in your ``.bash_profile``\ :
 
 .. code-block::
 
-   if [ -f ~/.bashrc ]; then
-     . ~/.bashrc
+   if [[ $- == *"i"* && -f ~/.bashrc ]]; then
+     source ~/.bashrc
    fi
 
 Refer to the official `Bash documentation <https://www.gnu.org/software/bash/manual/bashref.html#Bash-Startup-Files>`_ to get more info.

docs/themes-list/atomic.rst

@@ -36,7 +36,6 @@ Automatically via terminal
 
 
 #. You can install the theme automatically using the ``sed`` command from your Linux or OSX Terminal.
-#. On macOS, the ~/.bash_profile is used, not the ~/.bashrc.
 #. For installation on windows you should use `\ ``Git-Bash`` <https://git-for-windows.github.io/>`_ or make sure the terminal emulator you use (ej: cygwin, mintty, etc) has the ``sed`` command installed.
 
 Command to execute For Windows and Linux:
@@ -51,7 +50,7 @@ Command to execute for macOS:
 .. code-block:: bash
 
    # Set the "atomic" theme replacing the theme you are using of bash-it
-   sed -i '' 's/'"$BASH_IT_THEME"'/atomic/g' ~/.bash_profile
+   sed -i '' 's/'"$BASH_IT_THEME"'/atomic/g' ~/.bashrc
 
 Features
 --------

docs/themes-list/powerline-base.rst

@@ -8,7 +8,7 @@ all powerline themes.
 
 **IMPORTANT:** This theme requires that `a font with the Powerline symbols <https://github.com/powerline/fonts>`_ needs to be used in your terminal emulator, otherwise the prompt won't be displayed correctly, i.e. some of the additional icons and characters will be missing. Please follow your operating system's instructions to install one of the fonts from the above link and select it in your terminal emulator.
 
-**NOTICE:** The default behavior of this theme assumes that you have sudo privileges on your workstation. If that is not the case (e.g. if you are running on a corporate network where ``sudo`` usage is tracked), you can set the flag 'export THEME_CHECK_SUDO=false' in your ``~/.bashrc`` or ``~/.bash_profile`` to disable the Powerline theme's ``sudo`` check. This will apply to all ``powerline*`` themes.
+**NOTICE:** The default behavior of this theme assumes that you have sudo privileges on your workstation. If that is not the case (e.g. if you are running on a corporate network where ``sudo`` usage is tracked), you can set the flag 'export THEME_CHECK_SUDO=false' in your ``~/.bashrc`` to disable the Powerline theme's ``sudo`` check. This will apply to all ``powerline*`` themes.
 
 Provided Information
 --------------------
@@ -24,7 +24,7 @@ Provided Information
 * An indicator when connected by SSH
 * An indicator when ``sudo`` has the credentials cached (see the ``sudo`` manpage for more info about this)
 * An indicator when the current shell is inside the Vim editor
-* Battery charging status (depends on the battery plugin)
+* Battery charging status (depends on the battery library)
 * SCM Repository status (e.g. Git, SVN)
 * The current Kubernetes environment
 * The current Python environment (Virtualenv, venv, and Conda are supported) in use

docs/themes-list/powerline-multiline.rst

@@ -19,7 +19,7 @@ To get the length of the left and right segments right, a *padding* value is use
 In most cases, the default value (\ *2*\ ) works fine, but on some operating systems, this needs to be adjusted.
 One example is *macOS High Sierra*\ , where the default padding causes the right segment to extend to the next line.
 On macOS High Sierra, the padding value needs to be changed to *3* to make the theme look right.
-This can be done by setting the ``POWERLINE_PADDING`` variable before Bash-it is loaded, e.g. in your ``~/.bash_profile`` or ``~/.bashrc`` file:
+This can be done by setting the ``POWERLINE_PADDING`` variable before Bash-it is loaded, e.g. in your ``~/.bashrc`` file:
 
 .. code-block:: bash
 

docs/vcs_user.rst

@@ -10,7 +10,7 @@ Turn version control checking off to prevent slow directory navigation within la
 Controlling Flags
 ^^^^^^^^^^^^^^^^^
 
-Bash-it provides a flag (\ ``SCM_CHECK``\ ) within the ``~/.bash_profile`` file that turns off/on version control information checking and display within all themes.
+Bash-it provides a flag (\ ``SCM_CHECK``\ ) within the ``~/.bashrc`` file that turns off/on version control information checking and display within all themes.
 Version control checking is on by default unless explicitly turned off.
 
 Set ``SCM_CHECK`` to 'false' to **turn off** version control checks for all themes: