Skip to content

CLAUDE.md

Latest commit

 

History

History
158 lines (121 loc) · 6.05 KB

CLAUDE.md

File metadata and controls

158 lines (121 loc) · 6.05 KB

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

These documents guide ongoing maintenance, issue triage, and code quality improvements.