ShellCheck Deployment and Usage Guide

1. Prerequisites

Runtime Requirements

• Haskell runtime: ShellCheck is written in Haskell and requires a Haskell toolchain
• Shell environment: Used to analyze shell scripts (bash/sh)

Development Tools

• Cabal or Stack: Haskell build tools
• Git: For cloning the repository
• Make (optional): For building from source

System Dependencies

• Package manager: Required for system-level installation (apt, pacman, etc.)

2. Installation

Option 1: Install via Package Manager (Recommended)

Debian/Ubuntu:

sudo apt update
sudo apt install shellcheck

Arch Linux:

sudo pacman -S shellcheck

macOS (Homebrew):

brew install shellcheck

Option 2: Install via Haskell Toolchain

Using Cabal:

cabal update
cabal install ShellCheck

Using Stack:

stack update
stack install ShellCheck

Option 3: Install Pre-compiled Binary

Download the latest binary release from the GitHub Releases page and place it in your PATH.

Option 4: Build from Source

# Clone the repository
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck

# Install dependencies and build
cabal update
cabal install --dependencies-only
cabal build

# Install to system
cabal install

3. Configuration

Environment Variables

• No specific environment variables required for basic operation

Configuration Files

• ShellCheck uses default settings; no configuration files needed for standard use

Editor Integration

Configure your editor to use ShellCheck:

Vim/Neovim:

" Using ALE
let g:ale_linters = {'sh': ['shellcheck']}

" Using Syntastic
let g:syntastic_sh_checkers = ['shellcheck']

Emacs:

;; Using Flycheck
(add-hook 'sh-mode-hook 'flycheck-mode)

VSCode: Install the timonwong.shellcheck extension from the marketplace.

4. Build & Run

Running ShellCheck

Check a single script:

shellcheck yourscript.sh

Check multiple scripts:

shellcheck *.sh
shellcheck myscripts/*.sh

Check with specific options:

# Enable all warnings
shellcheck -x yourscript.sh

# Check with severity filtering
shellcheck -s warning yourscript.sh

# Output in different formats
shellcheck -f gcc yourscript.sh
shellcheck -f json yourscript.sh

Development Build

# From source directory
cabal build

# Run tests
cabal test

# Run with cabal
cabal exec shellcheck yourscript.sh

5. Deployment

Local Development

• Install via package manager or build from source
• Integrate with your editor for real-time feedback

CI/CD Integration

GitHub Actions:

- name: Run ShellCheck
  uses: ludeeus/action-shellcheck@master
  with:
    ignore: .git,.github

Travis CI:

script:
  - shellcheck myscripts/*.sh

CircleCI:

version: 2.1
orbs:
  shellcheck: circleci/shellcheck@x.y.z
jobs:
  build:
    steps:
      - shellcheck/check

GitLab CI:

shellcheck:
  stage: test
  script:
    - shellcheck myscripts/*.sh

Production Deployment

• Use system package manager for stable production environments
• Pin specific versions to avoid breaking changes from new ShellCheck releases
• Consider using pre-compiled binaries for consistent deployment across environments

6. Troubleshooting

Common Issues and Solutions

Issue: "shellcheck: command not found"

• Solution: Ensure ShellCheck is in your PATH
• Check installation with: which shellcheck
• Reinstall if necessary

Issue: Permission denied when running binary

chmod +x shellcheck
sudo mv shellcheck /usr/local/bin/

Issue: Build failures with Cabal

# Clean and rebuild
cabal clean
cabal update
cabal install --dependencies-only
cabal build

Issue: Missing dependencies

# Install system dependencies
sudo apt install libgmp-dev libffi-dev

# Or use Stack instead of Cabal
stack install ShellCheck

Issue: Editor integration not working

• Verify ShellCheck is installed and in PATH
• Check editor configuration matches your setup
• Test ShellCheck from terminal first

Issue: False positives or incorrect warnings

• Use ShellCheck's disable directives:

# shellcheck disable=SC1073

• Report bugs with minimal reproducible examples

Getting Help

• Documentation: man shellcheck or shellcheck --help
• Website: https://www.shellcheck.net
• GitHub Issues: https://github.com/koalaman/shellcheck/issues
• Wiki: https://github.com/koalaman/shellcheck/wiki

Version Management

# Check installed version
shellcheck --version

# Update via package manager
sudo apt update && sudo apt upgrade shellcheck

# Or reinstall via cabal/stack
cabal update && cabal install ShellCheck