Skip to content

README.md

Latest commit

 

History

History
224 lines (159 loc) · 7.49 KB

README.md

File metadata and controls

224 lines (159 loc) · 7.49 KB

Bash Development Template

Professional bash development environment with VS Code devcontainer, BATS testing, debugging, and AI integration

✨ Features

A comprehensive VS Code development container template designed for professional bash script development. This template provides a complete development environment with modern tooling, testing frameworks, debugging capabilities, and AI-enhanced workflows.

🛠️ Complete Toolchain

  • 🐳 Development Container: Ubuntu-based devcontainer with Zsh shell and custom setup tools
  • 🧪 Testing Framework: BATS-Core with assertion and support helper libraries
  • 🐛 Debugging Support: BashDB integration with VS Code debugging interface
  • ✅ Code Quality: ShellCheck linting and shfmt formatting with real-time feedback
  • 🤖 AI Integration: GitHub Copilot with custom instructions and MCP servers
  • 📁 Project Structure: Organized file layout for scalable bash projects
  • ⚡ Developer Experience: Custom aliases, themes, and VS Code task integration
  • 🔧 Setup Automation: Custom devcontainer tools for zsh plugins and configuration management

🏗️ Architecture

/
├── src/                         # Source bash scripts
├── test/                        # BATS test files and framework
│   ├── *.bats                  # Test implementations
│   ├── bats/                   # BATS core (submodule)
│   └── test_helper/            # Helper libraries (submodules)
├── .devcontainer/              # Container configuration
│   ├── devcontainer.json       # Main container config
│   ├── setup/                  # Custom setup tools
│   │   ├── install-zsh-plugins/    # Zinit plugin installer
│   │   ├── install-custom-config/  # Oh-my-zsh config loader
│   │   └── switch-apt-mirror/      # APT mirror switcher
│   └── etc/                    # Environment configurations
├── .vscode/                    # IDE configuration
│   ├── tasks.json              # Build and test tasks
│   ├── launch.json             # Debug configurations
│   └── settings.json           # Editor settings
├── .github/                    # AI instructions and metadata
└── docs/                       # Documentation and guidelines

🚀 Quick Start

Prerequisites

Getting Started

  1. Use this template to create a new repository or clone directly:

    git clone https://github.com/thecodecrate/devcontainer-bash.git my-bash-project
cd my-bash-project

  2. Open in VS Code:

    code .

  3. Reopen in Container when prompted, or use Command Palette:

    • Ctrl+Shift+P → "Dev Containers: Reopen in Container"

  4. Start developing! The environment includes:

    • Example script: src/example.sh
    • Example test: test/example.bats
    • Pre-configured tasks and debugging

First Steps

Run the example test to verify everything works:

# Using VS Code task (Ctrl+Shift+P → "Tasks: Run Task" → "Test (Bats)")
./test/bats/bin/bats test/

# Or run specific test file
./test/bats/bin/bats test/example.bats

Debug the example script:

  • Open src/example.sh
  • Set a breakpoint (click left margin)
  • Press F5 or use "Run and Debug" panel

📚 Development Workflow

Writing Scripts

  1. Create scripts in src/ directory following the shell style guide
  2. Add tests in test/ directory using BATS syntax
  3. Use VS Code features:
    • IntelliSense for bash commands and variables
    • Real-time ShellCheck linting
    • Format on save with shfmt

Testing

  • Run all tests: Use "Test (Bats)" task or ./test/bats/bin/bats test/
  • Run specific test: ./test/bats/bin/bats test/my_test.bats
  • Watch mode: Not built-in, but easy to add with file watchers

Debugging

  • Interactive debugging: Set breakpoints and press F5
  • Variable inspection: Use Debug Console and Watch panels
  • Step execution: Step into, over, and out of functions

Code Quality

  • Linting: ShellCheck runs automatically, see Problems panel
  • Formatting: Format on save enabled, or use Shift+Alt+F
  • Custom rules: Configure in .vscode/settings.json or .shellcheckrc

🔧 Customization

Adding Zsh Plugins

The template includes a custom tool for installing zsh plugins via zinit:

{
  "containerEnv": {
    "WITH_ZSH_PLUGINS": "zsh-users/zsh-autosuggestions zsh-users/zsh-syntax-highlighting"
  }
}

Custom Shell Configuration

Use the install-custom-config tool to automatically load custom scripts:

./.devcontainer/setup/install-custom-config/setup.bash --custom-dir /path/to/custom/scripts

APT Mirror Switching

For faster package installation in certain regions:

./.devcontainer/setup/switch-apt-mirror/setup.bash mirrors.kernel.org

VS Code Extensions

Add extensions to .devcontainer/devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "your.extension.id"
      ]
    }
  }
}

📋 Available VS Code Tasks

Task Description Shortcut
Test (Bats) Run all BATS tests Ctrl+Shift+P → Tasks
Lint Scripts Run ShellCheck on all scripts Available in task menu
Format Scripts Format all scripts with shfmt Available in task menu

🤖 AI Integration

This template includes comprehensive AI assistance:

GitHub Copilot

  • Custom instructions for bash development in .github/copilot-instructions.md
  • Context-aware suggestions for shell scripting patterns
  • Integrated with VS Code for seamless code completion

Model Context Protocol (MCP) Servers

Pre-configured MCP servers provide enhanced AI capabilities:

  • Brave Search: Web search for documentation and examples
  • Memory: Persistent project knowledge and context
  • Git: Repository operations and version control assistance
  • Filesystem: Secure file operations with access controls
  • Fetch: Web content retrieval and markdown conversion

📖 Documentation

🧰 Included Tools

Custom Devcontainer Tools

Development Tools

  • BATS-Core: Bash testing framework with helpers
  • BashDB: Interactive bash debugger
  • ShellCheck: Static analysis and linting
  • shfmt: Shell script formatting
  • Zinit: Fast zsh plugin manager

License

MIT License - Use this template freely for your projects.

Status: 🚧 In Development | Target: Professional Bash Development Environment | Maintainer: @thecodecrate