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

# 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

# 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

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 branches

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
• 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.