Repository: Bash-it/bash-it
Stars: 15024
CLAUDE.md
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
Run all tests using BATS (Bash Automated Testing System)
test/runRun specific test suites
test/run test/bash_it test/completion test/pluginsTests require git submodules to be initialized
git submodule init && git submodule updateLinting and Code Quality
The project uses a gradual pre-commit system implementation via clean_files.txt allow-list:
Run pre-commit hooks only on allow-listed clean files
./lint_clean_files.shRun pre-commit hooks on all files (for testing new coverage)
pre-commit run --all-filesManual shellcheck on bash files
shellcheck /*.bashFormat shell scripts
shfmt -w /*.bashGradual 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
Enable/disable components
bash-it enable alias git
bash-it enable plugin history
bash-it enable completion dockerShow available components
bash-it show aliases
bash-it show plugins
bash-it show completionsSearch components
bash-it search dockerKey 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 outputFile 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
Git Workflow
- NEVER commit directly to master branch
- Master should always stay in sync with
origin/master- Always create a feature branch for new work:
git checkout -b feature/feature-name- Keep feature branches focused on a single issue/feature
- Create separate branches for separate features
- Push feature branches with upstream tracking:
git push -u fork feature-branch-name- This allows manual pushes later with just
git push- Use
--force-with-lease for rebased branchesComponent 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}.batsCode Standards
- Use shellcheck for linting
- Follow existing code style in the repository
- Add appropriate metadata using composure functions
- Components should handle missing dependencies gracefully
- Prefix sensitive commands with
command to bypass user aliases:-
command mv instead of mv (users may have alias mv='mv -i')-
command grep instead of grep (users may have custom grep flags)-
command rm instead of rm (users may have alias rm='rm -i')- Apply to any command that could be aliased and break core functionality
- This prevents surprises from user's alias configurations in bash-it core functions
- Use parameter expansion with default for potentially unset variables:
-
${VARIABLE-} instead of $VARIABLE when variable may be unset- Prevents errors when
set -u is active in user's shell- Examples:
${BASH_VERSION-}, ${HOME-}, ${PATH-}- Critical for variables checked in conditionals:
if [ -n "${BASH_VERSION-}" ]- This defensive practice ensures scripts work regardless of user's shell options
Project Planning & Roadmaps
Strategic planning documents are maintained in docs/plans/:
- Quick Reference - TL;DR summary of current issues and action items
- Comprehensive Issue Analysis - Detailed breakdown of all open issues with categorization and recommendations
- 2025 Roadmap - 6-month technical debt reduction plan with phases and success metrics
These documents guide ongoing maintenance, issue triage, and code quality improvements.